I’ll build this as an implementation-ready roadmap without changing any files. I’m first auditing the existing app/docs and using the hackathon, community-wisdom, sponsor-tool, and challenge skills because your request mixes product architecture, current tool eligibility, and hackathon positioning.

The repository is a compact React/Vite frontend plus an Express/OpenCode workflow backend. I also found existing uncommitted documentation work and a .backboard/ directory; I’ll preserve both and treat them as current project context, not changes to overwrite.

The main architectural constraint is already clear: a Render-hosted browser cannot safely edit a user’s local repository by itself. The plan will therefore separate a hosted sandbox/demo path from a local full-project path, and only add a hosted-to-local connector as an explicitly secured later phase—not blur these into one unsafe mode.

The DevRelay MCP tools are not exposed in this session, but its local gateway CLI is available, so I’m using that same source for the required community pass instead of inventing community claims. No sponsor skills, credits, or accounts will be installed or claimed.

The current Maker stall is structural, not just copy: the HTTP request blocks for up to three minutes, no operation is persisted as RUNNING before execution, there is no event stream/polling endpoint, and the frontend has no cancel control. If the OpenCode call times out, the saved operation may lack a native session ID, so “reconcile” can be impossible. I’ll make that the first reliability phase.

Implementation plan

I audited the repository and produced the roadmap below without changing any files, packages, images, deployments, credentials, or commits. The current baseline is healthy: type-checking passes and all 22 tests pass.

The product should become:

An OpenCode-powered hackathon project builder that turns an unfinished idea into an approved plan, bounded implementation, verified evidence, and submission-ready demo.

OpenCode remains the only coding harness. Other tools are recommendations for projects created with Unfinished Business—not competing harnesses inside the product.

What the audit found

The Maker problem is architectural rather than cosmetic:

• The frontend waits for one long synchronous request and only shows a warning after eight seconds in App.tsx.
• The backend records the operation only after OpenCode returns in service.ts.
• OpenCode can run for up to 180 seconds without streaming visible progress in guide.ts.
• Cancel currently changes the saved status but does not interrupt the OpenCode session.
• The fixed model is hard-coded in client.ts.
• All four stage buttons are disabled, so users cannot inspect future or completed stages.
• Activity shows only four truncated results rather than a live execution trace.
• Local saved state contains repeated Authentication required failures, confirming that OpenCode onboarding must come before Maker.
• The project is currently single-workspace and single-user. Turning the public Render deployment into a shared multi-user filesystem agent would be unsafe without substantial isolation.

The uncommitted user changes in ENGINEERING_BLUEPRINT.md and .backboard/ must be preserved during implementation.

Product and experience direction

Use the positioning:

“Finish your hackathon project with a guided OpenCode workflow.”

The four characters become functional guides, not decorative mascots:

Guide	Purpose	Visual direction
Oracle	Clarifies the idea, audience, constraints, and success criteria	Spectral seer with a lantern orb
Architect	Creates the architecture, contracts, scope, and test strategy	Blueprint spirit with compass and animated construction lines
Maker	Runs bounded OpenCode implementation work	Friendly mechanical ghost with tool belt, sparks, and build states
Witness	Verifies evidence and prepares the demo and submission	Archival moth/eye spirit with scan beam and approval stamp

Theme: Ghostlight Hacker Workshop—deep navy and ultraviolet shadows, amber workbench light, terminal glow, layered blueprint cards, subtle glass and paper textures, and restrained 2.5D depth.

Animations should communicate state:

• Idle, listening, thinking, working, blocked, success, and error poses.
• Motion-powered card transitions, line drawing, parallax, progress pulses, and success stamps.
• prefers-reduced-motion alternatives.
• No heavy WebGL or continuously animated backgrounds that hurt performance.

The landing background should later be generated as a wide 21:9 image: a spectral hackathon workshop with an unfinished robot, terminal, blueprints, and four subtle spirits; dark navy/indigo with amber highlights, no text or logos, and quiet space behind the headline. Produce AVIF/WebP variants with a dark overlay and mobile crop. It has intentionally not been generated yet.

Phased implementation roadmap

Phase 0 — Protect the baseline and reorganize the plan

• Capture the current behavior, screenshots, routes, state schema, and failure modes.
• Preserve the existing dirty files.
• Decide the supported OpenCode version and pin compatibility to that version.
• Create a state-schema migration strategy before changing persisted project data.
• Define one canonical product brief, one engineering plan, and one decision log.
• Mark old documents as historical rather than silently overwriting them.

Acceptance:

• Existing projects still load.
• Current tests remain green.
• Every future phase has explicit documentation and migration requirements.

Phase 1 — Fix Maker reliability first

Replace the long synchronous request with an asynchronous run lifecycle:

1. POST /api/runs immediately saves a QUEUED run and returns 202 { runId }.
2. A runner creates the OpenCode session and saves its session ID before prompting.
3. The run moves through QUEUED → CONNECTING → RUNNING → WAITING_FOR_PERMISSION → VERIFYING → SUCCEEDED/FAILED/CANCELLED/UNKNOWN.
4. Subscribe to OpenCode events and normalize them into persisted run events.
5. Stream events to the UI using SSE with event cursors and reconnect support.
6. Refreshing the page reconnects to the existing run.
7. Cancel invokes OpenCode’s session interrupt endpoint.
8. A timeout becomes UNKNOWN or still-running—not a discarded session.
9. Reconciliation checks OpenCode before allowing a retry.
10. Double-submit protection prevents duplicate Maker runs.

The new Run Inspector should show:

• Connection and session creation.
• Selected model and reasoning variant.
• User-visible model updates.
• Tool calls with secrets redacted.
• Permission requests.
• Files inspected and changed.
• Diff summary.
• Commands and test results.
• Elapsed time, context use, tokens, and cost where exposed.
• Recovery, retry, interrupt, and final evidence.

Do not expose hidden chain-of-thought. Show operational events and concise model-authored progress summaries.

Acceptance:

• First progress appears within 500 ms.
• Maker never appears frozen.
• Refresh resumes the trace.
• Cancel actually stops the OpenCode run.
• The session ID is never lost on timeout.
• A terminal run contains a diff, verification evidence, and clear next action.

Phase 2 — Proper OpenCode onboarding and harness controls

OpenCode already exposes server, provider, model, session, permission, event, command, skill, MCP, and agent surfaces. The product should use these APIs rather than rebuilding them independently. OpenCode server documentation, provider setup, models and variants, and agents cover the relevant primitives.

Build a first-run connection wizard:

1. Detect whether OpenCode is reachable.
2. Explain how to install/start OpenCode locally.
3. Verify server URL and authentication.
4. Direct the user through OpenCode’s own provider connection process.
5. Fetch providers, models, capabilities, agents, and defaults.
6. Run a harmless connection test.
7. Save only connection metadata—not raw provider credentials.
8. Show repair instructions for authentication, missing models, unsupported tools, and version mismatch.

Expose contextually:

• Provider and model picker.
• Free, local, promotional, or paid status.
• Context/input/output limits.
• Tool, image, and reasoning support.
• Reasoning variants supported by the chosen model.
• Usage, context, tokens, and cost when OpenCode/provider data provides them.
• Agent selection and four project-specific agents.
• Permission policies: allow, ask, or deny.
• Pending permission requests.
• Sessions: list, resume, fork, compact, revert, interrupt, and export.
• Commands, skills, MCP servers, LSP, formatters, and tool availability.

Do not hard-code provider quota numbers; they change. Link users to provider billing or usage pages and display live facts only when available.

OpenCode-only boundaries:

• No Codex, Claude Code, Copilot, or alternate harness selection in the UI.
• Models from multiple providers are allowed only through OpenCode.
• Provider SDKs are not called directly by the core app.
• Backboard, Mastra, and similar services may be recommended for a generated project, but they do not replace OpenCode internally.

Phase 3 — Navigation, outlines, and project information architecture

Make all four character tabs selectable at all times:

• Completed tabs are reviewable.
• The active stage is editable.
• Future tabs show prerequisites, expected output, and a preview.
• Mutation buttons remain locked until prerequisites are satisfied.
• Store the selected tab in the URL.
• Add “Return to active task” and a persistent workflow status header.

Replace technical section titles with user-facing names while retaining stable internal IDs:

1. Vision & Success
2. Architecture
3. User Experience
4. OpenCode Setup
5. Tools & Budget
6. Validation
7. Build Roadmap
8. Demo & Launch

Every section card should include:

• Status and owner.
• Short summary.
• Dependencies.
• Last update.
• Stale reason.
• Edit/review action.
• Source evidence or related run.

Add a project dashboard containing readiness, blockers, current run, budget, tool recommendations, demo status, and submission checklist.

Phase 4 — Landing page and visual redesign

Landing page sections:

1. Hero: “Turn unfinished ideas into hackathon-ready builds.”
2. Primary actions: try the example, connect OpenCode, or set up locally.
3. Two usage modes.
4. Four-character workflow.
5. Interactive example.
6. OpenCode feature preview.
7. Idea-to-tool recommendation preview.
8. Local setup commands.
9. Privacy and security explanation.
10. Evidence/test philosophy.
11. FAQ.
12. Final CTA.

Interface improvements:

• Layered panels with shadow, texture, lighting, and depth.
• Stronger typography and section hierarchy.
• Responsive navigation and mobile run inspector.
• Skeletons and stage-specific progress states.
• Actionable empty, error, authentication, and timeout states.
• Consistent button hierarchy.
• Keyboard navigation, visible focus, WCAG contrast, reduced motion.
• Animated characters kept outside essential reading and interaction paths.

Phase 5 — Tool recommendation engine

The app should recommend tools based on the user’s idea, not show a sponsor wall.

Extract idea attributes such as:

• Web application
• AI inference or fine-tuning
• Tabular data
• Hardware
• Voice
• Browser automation
• Authentication
• Search
• Durable workflows
• Time-series data
• Remote database
• Public deployment

Each recommendation should show:

• Why it fits.
• Open-source/free/promotional status.
• Free allowance and important limits.
• Local or hosted setup.
• License.
• Estimated integration effort.
• Whether it helps a challenge category.
• Privacy or lock-in warning.
• “Add to plan” action—never automatic installation.

Tool filter for a solo hackathon builder

Tool	Recommendation
Render	Include conditionally. Free services work for a stateless demo, but free instances do not support the persistent disk this app currently uses. A reliable personal deployment will likely be paid. Render free limits
TabPFN	Recommend only for tabular classification/regression ideas. Free/open-weight for appropriate non-commercial use, subject to its model license.
Tinker	Promotional/conditional. Useful for model fine-tuning, but not a free ongoing default.
Arduino	Recommend for hardware ideas. Tooling and many designs are open source, but physical hardware costs money. Arduino licensing
DigitalOcean	Promotional only. Cloud credit is useful, but it is not a permanently free platform.
Gemma	Strong recommendation for local/open-weight AI through OpenCode and Ollama.
Auth0 for AI Agents	Conditional. Proprietary free tier; valuable only when the generated project needs user identity, delegated tool authorization, or multiple users. Auth0 pricing
Backboard	Promotional/conditional for memory or model routing. Do not use its CLI as the internal harness because the product is OpenCode-only.
ElevenLabs	Optional for speech and voice demos. Proprietary free tier with quota and usage restrictions. ElevenLabs pricing
Browserbase	Recommend Stagehand locally first; its core is open source. Browserbase’s hosted browser service has a small free allowance. Browserbase pricing, Stagehand
Entire	Strong recommendation and already enabled. Useful for preserving agent work, provenance, and recoverable sessions. Entire pricing
GitHub Copilot	Exclude from the product runtime and onboarding because it conflicts with the OpenCode-only direction.
Mastra	Open-source core, but do not use it for internal orchestration. Recommend only when a generated application itself needs an embedded agent framework. Mastra repository
MongoDB Atlas	Conditional. Proprietary hosted database with a free M0 tier; useful for remote multi-user or vector-backed projects, unnecessary for this app’s local-first default. Atlas pricing
Ultramarine	Promotional/paid only. Do not include in the default free catalog unless its current model license and credit offer are verified.
Sentry Agent Tracing	Strong recommendation and already integrated. Free developer tier and open-source SDKs; hosted Sentry itself is not fully OSI open source. Sentry licensing
SerpApi	Optional for projects requiring live search. Proprietary service with a limited free allowance. SerpApi pricing
.tech domain	Promotional only. Useful for a polished demo URL, but renewal is paid.
Temporal	Recommend for genuinely durable, resumable workflows. The server is open source and local development is free, but it is probably excessive for the first Maker fix. Temporal repository, self-hosting guide
Tiger Data	Conditional for time-series, telemetry, or vector workloads. Self-hosted open-source components are available; cloud usage is trial/paid.

Additional tools that fit this project:

• Ollama for local models through OpenCode.
• SQLite for durable single-user local state.
• Playwright for browser-level acceptance tests.
• axe-core for accessibility checks.
• OpenTelemetry for vendor-neutral event instrumentation.
• Mermaid for generated architecture diagrams.
• GitHub Actions for free public-repository CI.

Phase 6 — Hosted and local usage modes

The landing page should offer two clear paths.

Hosted demo/private deployment

• Public hosted instance provides the deterministic demo and optionally a restricted sandbox.
• It must not edit a visitor’s local filesystem.
• It must not store arbitrary visitor provider keys.
• Offer “Deploy your private copy to Render” for personal use.
• Store secrets in Render configuration and OpenCode credentials on the private persistent disk.
• Clearly label free versus paid infrastructure requirements.

Fully local mode

• App backend and OpenCode run on the user’s machine.
• Full repository access.
• Local provider credentials remain managed by OpenCode.
• Local models can run through Ollama.
• One-command development startup plus explicit production startup.
• Health checks explain which component is missing.

A remote browser-to-local connector may be investigated later, but it requires explicit pairing, HTTPS, loopback defaults, scoped short-lived tokens, origin restrictions, revocation, and a serious threat model. It should not block v1.

Phase 7 — Demo experience

Add a deterministic example that consumes no model quota:

• “Campus Umbrella Relay”: recover and finish a half-built campus lost-and-found application.
• Seed Oracle, Architect, Maker, and Witness outputs.
• Animate a simulated run trace.
• Show a representative diff, tests, and final submission package.
• Let users reset the example.
• Clearly label simulation versus a live OpenCode run.

Provide:

• “Try the example”
• “Watch the 90-second workflow”
• “Run it with my OpenCode”

This ensures a judge understands the product even if a provider is unavailable.

Phase 8 — Backend and security hardening

• Project/workspace selection with canonical path validation.
• Schema migrations and automatic backups.
• Atomic state writes and recovery from corruption.
• Run retention and cleanup policy.
• Secret redaction in logs, events, and Sentry.
• URL allowlisting and HTTPS requirements for remote OpenCode servers.
• SSRF protection.
• Origin and CORS enforcement.
• Session/SSE authentication.
• Rate limiting and maximum concurrent runs.
• Configurable time, token, and cost budgets per stage.
• Structured audit events.
• Provider rate-limit and quota handling.
• Permission prompts implemented in middleware/state, not prompt text.
• Remove duplicated or unused operation helpers after the async engine adopts or replaces them.
• Remove unused dependencies and environment variables only after references and migrations are verified.

Auth0 is not needed for the personal single-user version. Add it only if a later hosted edition becomes genuinely multi-user, with isolated projects, quotas, credentials, and storage.

Phase 9 — Testing and release gates

Required tests:

• State-schema migration tests.
• Provider/model capability normalization.
• Recommendation-engine rules.
• Queue, run, event, reconnect, restart, reconciliation, and cancellation.
• OpenCode unavailable, authentication failed, model missing, quota exceeded, permission denied, and test failure.
• Duplicate submission and stale run recovery.
• Local and hosted onboarding.
• Four-tab navigation and locked-action behavior.
• Deterministic demo reset.
• Responsive E2E coverage.
• Keyboard and accessibility checks.
• Visual snapshots for landing, each character, and error states.
• Secret redaction, path traversal, SSRF, CORS, and SSE authentication.
• Asset size and page performance budgets.

No release passes unless Maker survives reload, interruption, timeout, and provider failure without losing its OpenCode session.

Documentation and naming migration

Create this canonical structure:

• README.md — product overview and quickest path.
• docs/PRODUCT_BRIEF.md — audience, problem, differentiators, scope.
• docs/ARCHITECTURE.md — current and target architecture.
• docs/IMPLEMENTATION_PLAN.md — phased execution and acceptance gates.
• docs/OPENCODE_INTEGRATION.md — connection, providers, models, events, permissions, sessions.
• docs/LOCAL_SETUP.md — complete local installation.
• docs/HOSTED_DEPLOYMENT.md — Render/private deployment and limitations.
• docs/TOOL_CATALOG.md — recommendation matrix and license/cost metadata.
• docs/UX_AND_VISUAL_SYSTEM.md — theme, characters, motion, accessibility.
• docs/OPERATIONS_AND_RECOVERY.md — runs, cancellation, reconciliation, backups.
• docs/DEMO_AND_SUBMISSION.md — seeded demo, recording, challenge evidence.
• docs/DECISIONS.md — architectural decisions.
• docs/CHANGELOG.md — user-visible changes.
• docs/history/ — archived superseded documents.

Rename prompts to:

• ORACLE_PRODUCT_DISCOVERY.md
• ARCHITECT_ENGINEERING_PLAN.md
• MAKER_BUILD_AND_VERIFY.md
• WITNESS_DEMO_AND_SUBMISSION.md

Update the prompt loader and tests during that rename. Preserve Git history and place a superseded notice in old documents before archiving them.

Every implementation phase must update:

• Relevant architecture/setup document.
• Acceptance checklist.
• Decision log when behavior or scope changes.
• Changelog when user-visible behavior changes.

Recommended implementation order

For a strong submission, do not integrate every sponsor. Prioritize:

1. Maker reliability and live run inspector.
2. OpenCode connection and model configuration.
3. Selectable four-stage navigation.
4. Landing page, theme, and clear local/hosted setup.
5. Deterministic demo.
6. Documentation and evidence.
7. Tool recommender.
8. Advanced integrations and optional hosted features.

The current Hacktoberfest Week 4 “Ghost in the Machine” challenge is an unusually strong fit. Its deadline is October 31, 2026 at 11:59 PM PDT—November 1 at 12:29 PM IST—and it emphasizes a new open-source/open-weight AI project, working demo, public repository, and clear written explanation. Challenge page, official rules. The most defensible partner categories are Render, Entire, and Sentry because they are already meaningfully present; avoid adding shallow integrations merely to claim categories.

🌐 Community Wisdom

• Agent OS: A Local-First Harness Around Coding Models — @earthwalker17 argues for separating the planning brain from coding execution, requiring real build/test/browser evidence, and keeping recovery bounded. This strongly supports the proposed Maker/Witness split. Read Full Discussion on DEV

• OpenCode Ollama Setup: Run a Local AI Coding Agent — @koolkamalkishor highlights the privacy and control benefits of local OpenCode and Ollama, alongside the need to expose context-window, hardware, and tool-calling limitations. Read Full Discussion on DEV

• Human-in-the-Loop Agents in Pure Dart — @esratech recommends enforcing approvals in middleware with idempotent approval IDs and testing the resume path—not merely adding approval language to prompts. Read Full Discussion on DEV

No implementation has been performed. The safest starting sequence is Phase 0 followed immediately by the asynchronous Maker lifecycle in Phase 1.

I’ll turn the roadmap into a sequenced prompt pack, with one self-contained implementation prompt per phase. Each prompt will include scope boundaries, required documentation updates, verification commands, and completion criteria so it can be run safely in a fresh agent session.

The existing prompt directory contains the four product-stage procedures, so I’ll keep those intact and add a separate implementation-phases/ pack. This avoids confusing Oracle/Architect/Maker/Witness runtime prompts with prompts used to evolve the Unfinished Business codebase. I’ll also add ordering and handoff rules to the prompt index.

The first three prompts now cover baseline protection, Maker reliability, and OpenCode onboarding. I’m continuing with navigation, visual design, recommendations, and deployment modes; each prompt will explicitly name the documents it must keep synchronized.

All ten phase prompts are now drafted and indexed. I’m checking that their internal links resolve, that the prompt pack did not alter runtime behavior, and that the repository still passes its existing typecheck, tests, and production build.

Validation is complete: all ten phase prompts contain a documentation obligation and a stop/handoff gate; all local Markdown links resolve. Typecheck, all 22 tests, and the production build pass. The only build note is the pre-existing large-bundle warning, which the visual/release phases explicitly require measuring and addressing.

Created the complete Phase 0–9 implementation prompt pack:

• Implementation prompt index
• Main prompt-set documentation
• Project README

Each phase prompt includes:

• Prerequisites and repository inspection.
• Exact implementation scope and non-goals.
• Required tests and acceptance criteria.
• Relevant documentation that must be updated.
• Security and authorization boundaries.
• A mandatory phase handoff.
• A stop gate preventing automatic progression.
• No automatic deployment, spending, publication, credential changes, or commits.

The ten prompts cover baseline documentation, asynchronous Maker, OpenCode onboarding, workflow navigation, landing/visual system, tool recommendations, local/hosted modes, deterministic demo, security hardening, and final release/document migration.

Validation passed:

• All local documentation links resolve.
• npm run typecheck passed.
• All 22 tests passed.
• npm run build passed.
• git diff --check passed.

No product functionality was implemented. Your pre-existing changes to docs/ENGINEERING_BLUEPRINT.md and .backboard/ were preserved.