oracle

Files (13)

• SKILL.md
• openai.yaml · agents/
• artifact-template.html · assets/templates/
• html-artifacts.md · references/
• orchestration.md · references/
• project-workspace.md · references/
• quality-delivery.md · references/
• oracle_init.sh · scripts/
• oracle_lane_state.sh · scripts/
• oracle_legacy_manifest.sh · scripts/
• oracle_sandbox_worktree.sh · scripts/
• oracle_start_run.sh · scripts/
• oracle_scripts_test.sh · tests/

SKILL.md (first lines)

# Oracle

## Purpose

Package the user's normal engineering workflow so it does not need to be restated. Invoke the global skill as `$oracle init`, `$oracle plan`, or `$oracle implement` (natural-language `oracle ...` is equivalent). Oracle has three commands:

```text
oracle init [project root]
oracle plan <goal>
oracle implement <goal or plan>
```

Oracle combines five behaviors:

1. Create a durable `.artifacts/` workspace with human-readable project context and polished HTML artifacts.
2. Split separable work into parallel feature lanes with isolated Git state.
3. Give each lane fresh implementation, testing, and review threads.
4. Close every lane with project-specific `.artifacts/test.md` evidence and scored review.
5. Repeat failed lanes, integrate accepted lanes, then run final regression and release review.

## Commands

### `oracle init`

Initialize or repair the Oracle workspace without changing production behavior:

```bash
bash <oracle-skill-dir>/scripts/oracle_init.sh <resolved-root>
```

Create or repair the single `.artifacts/` workspace, including its durable `.oracle-workspace` state, `human.html`, `test.md`, `runs/`, `plans/`, `designs/workbench/`, `demos/`, `conclusions/`, `examples/`, and `sandbox/`. Preserve existing content. Inspect the project and replace starter placeholders with verified commands and architecture when practical. Plan and implementation runs require this initialized state and the matching manifest; they fail closed when either control is missing or damaged.

`.artifacts/human.html` is the polished internal codebase map for people and agents. `.artifacts/test.md` is the project-specific operating manual used by testing threads. Test evidence belongs under `.artifacts/runs/<run-id>/`.

If legacy root `.design`, `.sandbox`, `human.md`, or `test.md` content exists, initialization preserves it and creates `.artifacts/legacy-migration.md`, a fingerprinted manifest, and a pending status. The durable workspace state remembers that migration was seen even if the source and migration files are later removed. Read and reconcile the legacy content before planning or implementation. Runs remain blocked until `.artifacts/legacy-migration.status` is explicitly set to `reconciled`; never mark it reconciled without merging operational testing instructions and durable project knowledge. Added, changed, or removed content anywhere in the non-generated legacy tree resets the status to `pending`, and every run start recomputes the inventory so a stale reconciled marker cannot bypass the gate. If the legacy inventory becomes empty, verify the removals were intentional before reconciling it.

### `oracle plan`

Research and create a decision-grade plan without editing production source.

- Run initialization first when needed.
- Read `.artifacts/human.html`, `.artifacts/test.md`, repository instructions, product/design docs, source, tests, and relevant prior artifacts.
- Create real research threads for independent repo mapping, external research, architecture, UX, risk, and test strategy when parallel work improves the answer.
- Research threads may use private subagents for narrower fan-out.
- The orchestrator synthesizes facts, assumptions, alternatives, lane boundaries, dependencies, acceptance criteria, and verification into `.artifacts/plans/<run-id>-plan.html`.
- For UI work, use `.artifacts/designs/workbench/<run-id>/` for runnable variants and `.artifacts/designs/` for the exported decision record.
- Build every HTML plan from the HTML artifact standard. Use diagrams, timelines, comparison tables, matrices, or score plots only when they make relationships or evidence easier to understand.
- Plan mode is production-source read-only and artifact-write. Do not commit, push, or deploy.

### `oracle implement`

Implement the goal or matching plan through parallel closed-loop lanes.

- Run initialization and load the matching plan.
- Turn the current thread into the orchestrator for substantial or separable work. It manages intent, lanes, threads, resources, evidence, integration decisions, and artifacts; it does not write feature source.
- Split by independently shippable behavior, ownership, and mutable resources. Examples: CLI lane, web-app lane, backend lane, or multiple independent web feature lanes.
- Give each lane a unique branch/worktree, write scope, resource scope, and acceptance contract.
- Run each lane as a sequential three-thread loop: implementation thread, testing thread, then independent review/scoring thread.
- Run different lanes concurrently when their code and mutable resources do not overlap.
- When a lane fails, start a fresh implementation thread with the failed evidence, produce a new checkpoint, then start fresh testing and review threads. Do not ask the original writer to be its only reviewer.
- After lanes pass, use an integration thread to combine accepted checkpoints, then fresh regression-testing and final-review threads against the integrated revision.
- Update shared `.artifacts/human.html` and `.artifacts/test.md` only through the integration/docs owner after lane findings are reconciled.
- For visible work, capture a Peekaboo demo when practical.
- Create `.artifacts/conclusions/<run-id>-conclusion.html` with lane history, final diff, evidence, scores, limitations, and release status.

Words after a command describe the request. Testing, review, design, sandboxing, orchestration, demos, and conclusions are stages inside `plan` or `implement`, not additional commands.

## Real Thread Orchestration

For substantial `oracle implement` runs, real Codex threads are the durable phase boundaries. Private subagents are additional helpers inside those threads, not replacements for the implementation/test/review separation.

The orchestrator may use `list_projects`, `create_thread`, `read_thread`, `send_message_to_thread`, and related Codex task tools. Use a real worktree environment for every writing lane. Record every thread ID, role, branch, worktree, checkpoint, status, and artifact path in the run ledger.

Invoking `$oracle plan` or `$oracle implement` explicitly opts into the real role threads defined by this command contract. When Oracle is inferred from ordinary natural language rather than explicitly invoked, confirm thread creation once before calling user-visible task tools. If real-thread tools are unavailable, report the workflow as blocked; do not silently collapse implementation, testing, and review into one thread.

### Lane State Machine

```text
queued
  -> implementation thread writes and freezes checkpoint N
  -> testing thread follows .artifacts/test.md against checkpoint N
  -> review thread audits checkpoint N plus test evidence and scores it
  -> accepted
     OR findings -> fresh implementation thread -> checkpoint N+1 -> fresh test -> fresh review
```

Rules:

1. No implementation writer, tester, or reviewer operates on a moving revision.
2. Do not run test/review against a lane until its writer has exited and the checkpoint identity is frozen.
3. The testing thread does not fix source. It records reproducible failures and evidence.
4. The review thread is fresh, read-only, did not author the code, and receives the exact diff plus test evidence.
5. A fix round uses fresh threads. Reuse a thread only for a tightly related clarification, never as the only independent review.
6. No two active writers edit the same file or overlapping behavior, even in different worktrees.
7. One mutable resource has one owner at a time: browser profile, port, Clerk user, Convex deployment, database, fixture set, emulator/device, or provider sandbox.
8. Competing implementations are explicit alternatives. Select one; do not merge both automatically.
9. Role threads return structured results. The orchestrator alone materializes canonical ledgers, lane evidence, scorecards, and HTML artifacts in the root project; lane branches do not commit competing run-control files.
10. The orchestrator may write canonical artifacts but delegates source changes, testing, review, and integration to role threads.

## Parallel Lanes

Create as many lanes as the architecture supports; do not use a fixed thread count. A project with a CLI and a web app may have a CLI lane plus one or more independent web lanes, each running its own three-thread loop concurrently.

Do not create decorative parallelism. Two tasks belong in separate lanes only when they have:

- Disjoint or explicitly ordered source ownership.
- Independent acceptance criteria.
- Independent or schedulable mutable resources.
- A clear integration contract.

If two features share schemas, generated clients, migrations, core types, or the same live service state, extract a prerequisite lane or sequence them.

## Threads And Subagents

- The orchestrator creates and manages real Codex threads.
- Each real thread receives a narrow context packet rather than the full conversation.
- A worker thread may use private subagents for read-heavy exploration, logs, UI critique, or bounded disjoint work.
- Worker threads must not create more real Codex threads unless the orchestrator explicitly delegates lane coordination.
- Close completed private subagents promptly. Archive or clearly label completed real threads after their evidence is recorded.

From kausthubh-coder/skills, MIT.

More from kausthubh-coder/skills