Spec Kit v0.2 — Skills layer + sink catalog#2
Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b6bca26c02
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| For each stage in the agreed sequence, in order: | ||
|
|
||
| 1. **Pre-flight**: read `specs/<slug>/workflow-state.md` and confirm the upstream artifact status is `complete`. If not, return to that stage. |
There was a problem hiding this comment.
Step 2 explicitly supports Lean/Spike flows and later gating supports Skip <next stage>, but Step 4's pre-flight requires every upstream artifact to be complete. In any workflow where a stage is intentionally marked skipped, this instruction forces a rerun of the skipped stage and blocks forward progress, so the orchestrator cannot actually execute the documented skip paths.
Useful? React with 👍 / 👎.
| done | ||
| ``` | ||
|
|
||
| Treat features with `status: active` as resumable. Features with `status: complete` or `status: cancelled` should not auto-resume — offer "start new" instead. |
There was a problem hiding this comment.
This resume logic introduces complete/cancelled status handling, but the repository's workflow-state contract uses active | blocked | paused | done (and /spec:retro sets status: done). Mixing in non-schema values will misclassify finished workflows and can cause incorrect resume/cancel behavior when other commands parse state using the documented enum.
Useful? React with 👍 / 👎.
| ## After filing | ||
|
|
||
| - Notify the orchestrator that an ADR was filed (it will append to the `adrs_created` field in workflow state). | ||
| - The ADR is `Accepted` once the stage's quality gate passes. Until then it can be revised. |
There was a problem hiding this comment.
Allowing ADRs to be revised until a gate passes conflicts with the repo's ADR rule that existing ADR bodies are immutable and only supersession pointers/status may change. If agents follow this instruction, they can edit decision rationale in place instead of creating a superseding ADR, which breaks the audit trail the governance docs require.
Useful? React with 👍 / 👎.
Addresses three Codex review findings on PR #2: 1. orchestrate/SKILL.md (P1) — pre-flight validation now accepts both `complete` and `skipped` upstream artifact statuses, so Lean/Spike flows and the "Skip <next stage>" gate option actually work. Also clarifies that the Skip gate marks the *artifact* status as `skipped`, not the workflow's top-level `status`. 2. orchestrate/RESUME.md (P1) — replace the invented `complete` / `cancelled` workflow status values with the canonical enum `active | blocked | paused | done` from templates/workflow-state-template.md. Wrap-up now relies on /spec:retro setting `status: done`; no invented frontmatter fields. Cancellation isn't in the schema, so the Cancel gate becomes Pause; abandoning is documented as deleting the folder. Crash recovery talks about artifact statuses, not workflow status. 3. record-decision/SKILL.md (P2) — ADR bodies are immutable from creation per ADR-0001 ("Changes are made by superseding, not editing"). Removed the "until accepted, can be revised" license. Only status flips (Proposed → Accepted → Superseded) and supersession pointers may change. Even pre-acceptance corrections go through supersession. https://claude.ai/code/session_01PTc1UHovmBA1Psbd3719KD
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3e5da63b81
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| ls specs/ 2>/dev/null | ||
| ``` | ||
|
|
||
| For each `specs/<slug>/workflow-state.md` whose `status: active`, list `slug | current_stage | last_updated`. Then **batch one `AskUserQuestion`** asking the user to pick: |
There was a problem hiding this comment.
Step 1 only considers workflow-state.md files where status: active, but the same skill's pause gate sets features to status: paused. In practice, a user who paused a feature and later asks “what’s next?” won’t see it offered for resume, which breaks the advertised pause/resume flow and pushes them toward starting a new feature unintentionally.
Useful? React with 👍 / 👎.
| 3. **Depth**: `Standard` (all 11 stages, recommended) / `Lean` (skip Idea + Research; jump to Requirements) / `Spike` (Idea + Research only, no implementation). | ||
| 4. **Optional gates**: multi-select — `Run /spec:clarify after Requirements`, `Run /spec:clarify after Design`, `Run /spec:analyze after Tasks`. |
There was a problem hiding this comment.
The new depth option allows Lean (skip Idea/Research) and stage-gate skip options, but stage commands still require upstream artifacts to be complete (for example, /spec:requirements requires both idea.md and research.md complete, and /spec:specify requires design.md complete). Because /spec:start initializes those artifacts as pending and this flow never defines a mandatory transition to skipped before dispatch, selecting Lean/skip can dead-end at the very next command instead of progressing.
Useful? React with 👍 / 👎.
|
|
||
| ## Cross-stage helpers | ||
|
|
||
| - **ADR detected mid-stage:** any subagent may flag a decision that needs an ADR. The orchestrator should run `/adr:new "<title>"` on the user's behalf (after a one-question `AskUserQuestion` confirmation) and append the ADR path to `workflow-state.md` `adrs:` list. |
There was a problem hiding this comment.
adrs writes from workflow-state
This helper instructs the orchestrator to append ADRs to an adrs: list in workflow-state.md, but the canonical workflow-state schema does not define that field. Adding undocumented frontmatter keys creates incompatible state files for tooling that parses only the documented enum/fields and conflicts with nearby guidance that the schema is fixed.
Useful? React with 👍 / 👎.
… up front; drop adrs: frontmatter field Addresses three more Codex findings on PR #2: 1. orchestrate/SKILL.md (P1) — Step 1 resume detection now lists workflows with status `active`, `paused`, or `blocked`. Previously only `active` was considered, so users who paused via the gate couldn't resume — exactly the flow the skill advertises. 2. orchestrate/SKILL.md (P1) — added new Step 3.5 that explicitly marks artifacts as `skipped` in workflow-state.md *before* dispatching any stage, so Lean (skip Idea + Research), Spike (skip stages 5–11 except retro), and per-stage Skip gates actually let the next slash command pass its precondition check. Lean/Spike now perform the skip-marking up front; the per-stage Skip gate marks the next stage's artifact before continuing. This is the one place the orchestrator owns artifact-status edits; slash commands own the rest. 3. PHASES.md, record-decision/SKILL.md, docs/sink.md (P2) — removed the invented `adrs:` (and `notes:`) frontmatter field references. ADR paths and skill-level notes now go into the existing `## Hand-off notes` free-form section as dated one-line entries. The frontmatter schema in templates/workflow-state-template.md stays fixed; the prohibition is now stated explicitly. https://claude.ai/code/session_01PTc1UHovmBA1Psbd3719KD
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a66b42c992
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| ### Stage 10 — Release (`/spec:release`) | ||
| - **Initial:** dispatch as-is. | ||
| - **Pre-flight check:** confirm `review.md` verdict is `ship` or `fix-then-ship` with all P0 closed. |
There was a problem hiding this comment.
This pre-flight check expects review.md verdicts of ship or fix-then-ship, but the canonical review outputs are Approved, Approved with conditions, and Blocked (see templates/review-template.md and /spec:review). If the orchestrator follows this instruction, valid reviews can be misclassified and Stage 10 can be blocked despite a passing review. Align the accepted verdict values with the review artifact schema.
Useful? React with 👍 / 👎.
| 2. Diff what the agent reports against the current map: | ||
| - **New term coined?** Add to `Core concepts`. | ||
| - **New invariant discovered?** Add to `Invariants` and stop the workflow to confirm with the user — invariants are load-bearing. | ||
| - **Context boundary changed?** Update the table and run a one-question `AskUserQuestion` to confirm with the user. |
There was a problem hiding this comment.
In the “invoked from a stage agent (typical)” flow, this step tells the agent to run AskUserQuestion, but the orchestrator contract in this same change states subagents cannot use AskUserQuestion (see .claude/skills/orchestrate/SKILL.md). That makes the primary domain-context path fail when a context boundary changes, because the tool call is unavailable from subagent context. Route this confirmation through the orchestrator/main thread instead.
Useful? React with 👍 / 👎.
| Open `specs/<slug>/workflow-state.md` and: | ||
|
|
||
| - **Depth = Lean**: set `idea.md: skipped` and `research.md: skipped` in the `artifacts:` map; add two lines to the `## Skips` section, e.g. `idea.md: skipped — Lean depth, scope captured directly in requirements`. Update the human-readable status table to match. | ||
| - **Depth = Spike**: set `spec.md`, `tasks.md`, `implementation-log.md`, `test-plan.md`, `test-report.md`, `review.md`, `traceability.md`, `release-notes.md` all to `skipped`; add a single `## Skips` entry: `spike depth — research-only run, no implementation`. (Stage 11 retrospective is never skipped per `docs/spec-kit.md` §3.11.) |
There was a problem hiding this comment.
Spike is defined earlier as “Idea + Research only,” but this skip list omits requirements.md and design.md. Those artifacts remain pending, so a Spike run either requires extra manual skip interventions or fails later pre-flight checks that require all upstream artifacts to be complete or skipped. Include requirements and design artifacts in the upfront Spike skip set so the declared depth is actually executable.
Useful? React with 👍 / 👎.
| - `Continue to <next stage>` (Recommended) | ||
| - `Pause here` — set `status: paused` in `workflow-state.md` and exit; resume by re-invoking `/orchestrate`. | ||
| - `Re-run <this stage> with feedback` (free-text in "Other" — pass as additional context to the slash command). | ||
| - `Skip <next stage>` — open `workflow-state.md`, set the next stage's artifact status from `pending` to `skipped` in the `artifacts:` map and the human-readable table, append a one-line reason to the `## Skips` section, bump `last_updated`. This is required *before* dispatching the stage after the skipped one — otherwise its slash command will reject upstream as `pending`. Never mark the workflow's top-level `status` as anything other than `active | blocked | paused | done`. |
There was a problem hiding this comment.
The skip action updates only a singular “next stage artifact,” but some stages own multiple artifacts (e.g., testing and review in templates/workflow-state-template.md). Skipping only one leaves sibling artifacts pending, which then violates the orchestrator’s own upstream pre-flight rule and blocks subsequent stages. The skip path should transition all artifacts for that stage to skipped together.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ff20db3acb
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - `Continue to <next stage>` (Recommended) | ||
| - `Pause here` — set `status: paused` in `workflow-state.md` and exit; resume by re-invoking `/orchestrate`. | ||
| - `Re-run <this stage> with feedback` (free-text in "Other" — pass as additional context to the slash command). | ||
| - `Skip <next stage>` — open `workflow-state.md`, set **every artifact owned by the skipped stage** from `pending` to `skipped` in the `artifacts:` map and the human-readable table, append one `## Skips` line per artifact (or one summary line naming the stage), bump `last_updated`. Some stages own multiple artifacts and they must all be skipped together: stage 4 (Design) → `design.md`; stage 8 (Testing) → `test-plan.md` + `test-report.md`; stage 9 (Review) → `review.md` + `traceability.md`. This is required *before* dispatching the stage after the skipped one — otherwise its slash command will reject the upstream stage as `pending`. Never mark the workflow's top-level `status` as anything other than `active | blocked | paused | done`. |
There was a problem hiding this comment.
This gate always offers Skip <next stage>, including stage 9 (Review), but stage 10 still requires a review verdict before release (.claude/commands/spec/release.md step 1). If Review is skipped here, review.md/traceability.md become skipped and the next release step cannot satisfy its own pre-flight, so the advertised skip path can dead-end the workflow.
Useful? React with 👍 / 👎.
|
|
||
| 1. Read the full `workflow-state.md` and report a one-line summary to the user (current stage, status, last agent, last update). | ||
| 2. Read the most recent stage's artifact to confirm it actually completed (don't trust state alone — the file may have been deleted or edited). | ||
| 3. Determine the next pending stage from the artifacts table in `workflow-state.md`. |
There was a problem hiding this comment.
This instructs resume logic to choose the next stage from the human-readable artifacts table, but the workflow-state schema defines the YAML artifacts map as canonical and the table as a view (templates/workflow-state-template.md, line 8). If those diverge, resume can pick the wrong stage and trigger incorrect re-runs/skips; this should read frontmatter artifacts statuses instead.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b5ddbf3c87
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| Run **stage 3 — Requirements**. | ||
|
|
||
| 1. Resolve slug; verify `idea.md` and `research.md` are `complete`. | ||
| 1. Resolve slug; verify `idea.md` and `research.md` are each `complete` or `skipped` (per the artifact-status enum). Lean depth marks both as `skipped` up front; treat that as passable. |
There was a problem hiding this comment.
This pre-flight allows /spec:requirements to run when idea.md and research.md are skipped, but the PM agent still treats both as mandatory inputs (.claude/agents/pm.md reads them first). In the Lean path, those artifacts are explicitly marked skipped without being created, so Stage 3 can proceed with missing source documents and either fail or produce ungrounded requirements. Keep Stage 3 gated on real upstream artifacts, or define an explicit Lean input contract for the PM agent.
Useful? React with 👍 / 👎.
| **Skip-forbidden stages** — do not offer Skip for these (downstream gates on artifact *content*, not just status, so a `skipped` upstream dead-ends the next command): | ||
| - Stage 7 (Implementation) — `/spec:test` needs implementation tasks marked `done` in `tasks.md` to test against. | ||
| - Stage 8 (Testing) — `/spec:review` requires `test-report.md` to have no S1/S2 open. | ||
| - Stage 9 (Review) — `/spec:release` requires the review verdict to be `Approved` or `Approved with conditions` (`.claude/commands/spec/release.md` step 1). A `skipped` review has no verdict. | ||
| - Stage 11 (Learning / retrospective) — never skipped per `docs/spec-kit.md` §3.11. |
There was a problem hiding this comment.
The skip-forbidden list excludes stages 5 and 6, so users can skip Specification or Tasks and then continue into commands that require those artifacts. /spec:tasks is defined as decomposing spec.md, and /spec:implement resolves the next task from tasks.md; if either stage is skipped, the next stage has no canonical input and the workflow dead-ends. Add stages 5 and 6 to the skip-forbidden set (or generate equivalent replacement artifacts before continuing).
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9a9f12ac69
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| Run **stage 5 — Specification**. | ||
|
|
||
| 1. Resolve slug; verify `requirements.md` and `design.md` are `complete`. | ||
| 1. Resolve slug; verify `requirements.md` and `design.md` are each `complete` or `skipped` (per the artifact-status enum). |
There was a problem hiding this comment.
This pre-flight now accepts requirements.md and design.md as skipped, but the Stage 5 owner explicitly depends on both artifacts as mandatory inputs (.claude/agents/architect.md, “Read first”). In any manual or recovered workflow where those files were skipped or missing, /spec:specify can still run and generate a spec without canonical requirements/design context, which then propagates bad inputs to task planning and review.
Useful? React with 👍 / 👎.
| Run **stage 6 — Task planning**. | ||
|
|
||
| 1. Resolve slug; verify `spec.md` is `complete`. | ||
| 1. Resolve slug; verify `spec.md` is `complete` or `skipped` (per the artifact-status enum). |
There was a problem hiding this comment.
Allowing Stage 6 to proceed when spec.md is skipped removes the planner’s primary source artifact (.claude/agents/planner.md reads spec.md first). That means tasks can be produced without implementation contracts, breaking the expected SPEC→T traceability and causing downstream execution to follow an invented plan instead of the approved specification.
Useful? React with 👍 / 👎.
| Run **stage 9 — Review**. | ||
|
|
||
| 1. Resolve slug; verify the test report is `complete` and there are no S1/S2 open. | ||
| 1. Resolve slug; verify the test report is `complete` or `skipped` (per the artifact-status enum) and that, if `complete`, there are no S1/S2 open. |
There was a problem hiding this comment.
The updated gate allows review to run with test-report.md: skipped, and only enforces the S1/S2 check when the report is complete. This permits Stage 9 to produce a release-signaling verdict without Stage 8 evidence, even though the reviewer contract expects test-plan.md and test-report.md as core review inputs (.claude/agents/reviewer.md). Review should stay blocked unless test reporting is complete.
Useful? React with 👍 / 👎.
| 1. **One active feature, no `$ARGUMENTS`:** offer to resume it as the recommended option, plus "Start new feature" alternative. | ||
| 2. **Multiple active features:** list each as an `AskUserQuestion` option. If there are >4, sort by `last_updated` desc and offer the top 3 plus "Start new feature". | ||
| 3. **`$ARGUMENTS` matches a known slug:** resume that one without asking. | ||
| 4. **`$ARGUMENTS` is a goal phrase, no match:** propose deriving a slug and starting fresh. | ||
| 5. **No active features and no `$ARGUMENTS`:** ask for the goal. |
There was a problem hiding this comment.
This file defines paused and blocked as resumable statuses, but the decision flow only branches on “active” features. In sessions with no active workflow but one paused/blocked workflow, the resume picker can miss the actual resumable item and steer users toward starting a new feature unintentionally. The decision logic should include all resumable statuses consistently.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 7b4bf48ece
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - **Never** ask more than one `AskUserQuestion` per gate. Batch options into a single question. | ||
| - **Always** update `workflow-state.md` between stages (delegated to the slash commands). | ||
| - **Always** use the same slug across all artifacts in one feature. | ||
| - **Never** write to `specs/<slug>/` directly — the stage subagents own those files. |
There was a problem hiding this comment.
This constraint directly conflicts with Step 3.5 in the same skill, which requires the orchestrator to create Lean stub artifacts and update workflow-state.md for depth-driven skips. In practice, if the agent follows this hard “Never write to specs/<slug>/ directly” rule, it will skip the required stub/write step and then /spec:requirements will escalate because idea.md/research.md content is missing. Add an explicit exception here for orchestrator-owned depth initialization edits.
Useful? React with 👍 / 👎.
| 5. Commit (or mark as ready to commit if the user hasn't authorized commits) with message `red: <behavior in plain English>`. | ||
|
|
There was a problem hiding this comment.
The skill instructs per-cycle commits like red: ..., which conflicts with the implementation command’s required task-ID commit format (feat(<area>): <task-id> ...) and the repo’s traceability convention. When the dev agent follows this skill, commit history no longer maps cleanly back to T-<AREA>-NNN tasks, making workflow auditing and task-level progress tracking unreliable.
Useful? React with 👍 / 👎.
| | `docs/spec-kit.md`, `docs/quality-framework.md`, `docs/traceability.md`, `docs/ears-notation.md` | Human | Versioned (v0.1, v0.2…) | | ||
| | `docs/sink.md` | Human | Versioned alongside spec-kit | | ||
| | `docs/steering/*` | Human | Updated as project evolves | | ||
| | `docs/adr/NNNN-*.md` | Architect / any agent that flags | **Immutable once Accepted**; supersede via new ADR | |
There was a problem hiding this comment.
This row allows ADR bodies to remain editable until acceptance, but the ADR template and repo governance define ADR bodies as immutable from creation (only status/supersession pointers may change). Following this guidance would permit in-place edits to proposed ADR rationale and weaken the audit trail other workflow steps rely on.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a6e1b376f6
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| ## The cycle | ||
|
|
||
| For each task in `tasks.md`: |
There was a problem hiding this comment.
This skill tells the dev agent to run the cycle for each task in tasks.md, but /spec:implement is explicitly scoped to a single task per invocation (.claude/commands/spec/implement.md, step 1/10/12). If followed literally, one Stage 7 run can consume the whole backlog (including tasks that should be separately gated), which bypasses per-task orchestration, task-state transitions, and handoffs. Scope this procedure to the currently dispatched task ID, then return control to the orchestrator.
Useful? React with 👍 / 👎.
| - **Optional gate:** offer `/spec:analyze` after this stage if the user enabled it. This is the strongest natural place for `/spec:analyze` — it cross-checks REQ → SPEC → T coverage. | ||
|
|
||
| ### Stage 7 — Implementation (`/spec:implement`) | ||
| - **Initial:** dispatch with the first task ID from `tasks.md` (`/spec:implement T-<AREA>-001`). The dev agent walks the dependency-ordered list one task at a time. |
There was a problem hiding this comment.
The Stage 7 dispatch template only describes an initial call with the first task ID and then implies the dev agent will walk the rest, but /spec:implement executes one task per call. In workflows with multiple implementation tasks, this guidance causes orchestration to advance after the first task (or re-run T-...-001), leaving remaining tasks undone and blocking later stages. The Stage 7 template should explicitly loop dispatches until no ready implementation tasks remain.
Useful? React with 👍 / 👎.
| 1. Read the current `docs/CONTEXT.md` if it exists. If not, scaffold from the template above. | ||
| 2. Diff what the agent reports against the current map: |
There was a problem hiding this comment.
This procedure always reads/scaffolds docs/CONTEXT.md, even though the same skill declares a multi-context layout (docs/CONTEXT-MAP.md + docs/contexts/<name>.md). In repositories that have switched to multi-context mode, following this step creates or updates the wrong file and introduces a second source of truth for context boundaries. Add a branch that targets CONTEXT-MAP.md/docs/contexts/*.md when multi-context mode is active.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 22f9939ead
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| ### Stage 7 — Implementation (`/spec:implement`) | ||
| - **One task per dispatch.** `/spec:implement` is scoped to a single task per call (`.claude/commands/spec/implement.md` step 1). The dev agent does **not** walk the backlog inside one invocation; the orchestrator must loop dispatches until no ready implementation tasks remain. | ||
| - **Initial dispatch:** read `tasks.md`, find the first ready task (dependencies satisfied per its `Blocked by:` field, no blockers, status `pending`), dispatch `/spec:implement <T-AREA-NNN>`. Wait for return. | ||
| - **Loop:** after each task returns, mark its task status as `done` in `tasks.md`, re-scan for the next ready task in dependency order, dispatch again. Continue until either (a) all implementation tasks are `done` (advance to gate), (b) the next ready task is gated for human oversight (gate now), or (c) the dev agent reports `blocked` (escalate). |
There was a problem hiding this comment.
The Stage 7 loop currently says to mark a task done immediately after every /spec:implement return, before handling the documented blocked outcome. In runs where the dev agent reports a blocker or incomplete execution, this will still advance task state and can make downstream stages (especially /spec:test) run against unfinished work. The loop should only mark done when the command explicitly completed the task successfully.
Useful? React with 👍 / 👎.
|
|
||
| > "The last run appears to have crashed during `<stage>` at `<timestamp>`. Do you want to re-run it from scratch, or has work since been done that I should re-detect?" | ||
|
|
||
| Offer: `Re-run <stage>` (Recommended) / `Mark artifact complete and continue` (only if the user can confirm the artifact really is done — flips that artifact's status from `in-progress` to `complete`) / `Inspect manually first`. |
There was a problem hiding this comment.
This recovery branch is entered when the artifact is in-progress but the file was never written, yet it still offers Mark artifact complete and continue. Choosing that path can leave workflow-state.md claiming completion without any artifact on disk, and resume logic later trusts artifact statuses to pick the next stage, which can advance the workflow with missing required inputs. The safe options here are re-run or manual inspection/reconstruction, not direct completion.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e6c1433d62
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| Run a `grill` session focused on the current state of `CONTEXT.md`: | ||
|
|
There was a problem hiding this comment.
The direct-invocation branch still hard-codes CONTEXT.md, so in repositories already using multi-context layout (docs/CONTEXT-MAP.md + docs/contexts/*.md) this path can update or recreate the wrong file and split domain truth across two locations. Even though the stage-agent path now detects mode, this direct-user path should apply the same detection before deciding which context files to grill/update.
Useful? React with 👍 / 👎.
| ## After filing | ||
|
|
||
| - Notify the orchestrator that an ADR was filed; the orchestrator records the ADR path as a dated line in the `## Hand-off notes` section of `workflow-state.md` (no schema fields are added). | ||
| - **ADR bodies are immutable from creation** (per ADR-0001: "ADRs are immutable. Changes are made by superseding, not editing."). Only the YAML `status` field (`proposed` → `accepted` → `deprecated` → `superseded by ADR-NNNN`, all lowercase per `templates/adr-template.md`) and the `superseded-by` / `supersedes` pointers may change after the file is written. Rationale, context, decision text, alternatives, and consequences are frozen. |
There was a problem hiding this comment.
supersedes immutable after ADR creation
This rule allows changing both superseded-by and supersedes after an ADR is written, but the repo contract only allows mutating the predecessor ADR's status and superseded-by pointer. Permitting post-hoc edits to supersedes enables rewriting decision lineage and weakens the audit trail that ADR immutability is meant to preserve.
Useful? React with 👍 / 👎.
Adds a mattpocock-style skills layer on top of the v0.1 Spec Kit foundation, integrated cleanly with PR #3's operational learnings (.claude/memory, .claude/settings.json, agents/operational/, docs/branching|verify-gate|worktrees.md). Skills (.claude/skills/): - orchestrate — natural-language entry to the 11-stage workflow. Reads workflow-state.md, gates with AskUserQuestion, dispatches /spec:* commands per stage. Lean depth writes idea/research stubs marked complete; Spike marks stages 3–10 skipped (none dispatched); per-stage Skip allowed only for stage 10. Crash-safe resume protocol against the canonical YAML artifacts: map. (SKILL.md + PHASES.md + RESUME.md, progressive disclosure pattern.) - grill — one-question-at-a-time interview primitive (after Pocock). - design-twice — parallel divergent design via Task tool (Ousterhout). /spec:design now reads the design-comparison.md synthesis as input. - tracer-bullet — vertical-slice planning for /spec:tasks. - tdd-cycle — strict red/green/refactor scoped to one /spec:implement task; canonical task-ID commit format for traceability. - record-decision — wraps /adr:new with ADR-worthiness criteria. ADR bodies immutable from creation; only YAML status and supersession pointers may change. - domain-context — lazy maintenance of docs/CONTEXT.md (or multi-context layout); subagent-safe via [CONTEXT-CONFIRM] flag. - ubiquitous-language — lazy maintenance of docs/UBIQUITOUS_LANGUAGE.md. Sink catalog (docs/sink.md): one source-of-truth document for every markdown artifact — workflow-scoped (specs/<slug>/*.md), cross-cutting (docs/adr/, docs/CONTEXT.md, docs/UBIQUITOUS_LANGUAGE.md), governance, and tooling. Documents ownership, eager vs. lazy, immutability, naming, and read order for stage subagents. v0.1 command updates (precondition rigor, integrating with PR #3): - /spec:design now reads design-comparison.md from design-twice and passes it to all three design subagents as input context. - /spec:release verdict check now explicitly accepts both Approved and Approved with conditions (per templates/review-template.md). - /spec:* preconditions reaffirm `complete`-only upstream and cite the agents that depend on the content (Lean stubs satisfy this; Spike never dispatches against skipped artifacts). Skills README, root README, and CLAUDE.md updated to surface the combined catalog (workflow conductor + practice skills + cross-cutting sink + operational skills from PR #3) and bump version to v0.2. Iterated through ~10 rounds of Codex review (~26 comments addressed) plus self-reviews via parallel subagents (schema, slash-command preconditions, subagent contracts, cross-skill consistency, scenario walkthrough). https://claude.ai/code/session_01PTc1UHovmBA1Psbd3719KD
Luis85
force-pushed
the
claude/orchestrator-workflow-subagents-pAZox
branch
from
e6c1433 to
d2b360d
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d2b360dfa7
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| 1. **Confirm the decision is ADR-worthy** against the three criteria above. If two of three fail, decline and recommend inline documentation. | ||
| 2. **Pick the next ADR number** — find the highest number under `docs/adr/` and add 1, zero-padded to 4 digits. | ||
| 3. **Invoke `/adr:new "<title>"`**. The slash command scaffolds `docs/adr/NNNN-<slug>.md` from `templates/adr-template.md`. |
There was a problem hiding this comment.
This step requires invoking /adr:new, but stage subagents are explicitly documented as unable to run slash commands (for example, .claude/agents/architect.md says not to call /adr:new from subagent context). Because this skill is positioned for architect/stage-agent use, following it during /spec:design will fail at ADR creation time and can leave required architecture decisions undocumented; the flow should hand off ADR creation to the orchestrator/main thread (or provide a subagent-safe direct-file path).
Useful? React with 👍 / 👎.
| Run **stage 2 — Research**. | ||
|
|
||
| 1. Resolve slug; verify `specs/<slug>/idea.md` exists and is `complete`. If not, escalate. | ||
| 1. Resolve slug; verify `specs/<slug>/idea.md` exists and is `complete`. (Lean depth produces a stub marked `complete`; Spike depth never invokes this command since stages 3+ are not dispatched.) If `pending`, `in-progress`, `blocked`, or `skipped`, escalate. |
There was a problem hiding this comment.
This preflight note says Spike depth never invokes /spec:research, but Spike is defined elsewhere in this change as an Idea + Research flow. That contradiction can cause orchestrator/agent behavior that skips Stage 2 in Spike runs, leaving research.md absent in the very mode that is supposed to produce research output.
Useful? React with 👍 / 👎.
PR #143 review feedback (Codex P2 round 3): item #2 only covered **new** CSS/JSX/HTML files. The severity model treats token literals in any changed code as blocking, so adding `#fff` to an existing file like `sites/foo.css` (or inline `style="…"` in modified JSX) bypassed the gate. - .claude/agents/brand-reviewer.md item #2: scope widened to "changed (new *or* modified)" files reported by `git diff --name-only "$BASE"...HEAD`. Same :root-stripping awk + hex grep recipe as item #1. Inline `style="…"` attributes in changed JSX/HTML are explicitly in scope. - templates/brand-review-checklist.md: same widening. Refs PR #143, Codex review round 3. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Round-5 finding on PR #143: brand-reviewer triggers on the full .claude/skills/specorator-design/** tree, but item #2's blocking hex scan only listed sites/ and .claude/skills/specorator-design/ui_kits/. A PR adding a literal hex to e.g. specorator-design/slides/*.jsx or preview/*.html would slip past the gate. Widen item #2's path scope to .claude/skills/specorator-design/ in both the agent prompt and the author-facing checklist. The check mechanics are unchanged.
(P1 #1) Workflow permissions check now scans `jobs.<job>.permissions` too, not only the workflow-level block. GitHub Actions applies job-level permissions after workflow-level, so a compliant top-level can be widened by a job override (e.g. `actions: write`). Each declared block — top-level or per-job — must be subset+match against the least-privilege set. Top-level still requires presence; job-level blocks are optional but if present must not widen scope. (P1 #2) `package.json#files` is now enforced against the contract include list. Added `EXPECTED_PACKAGE_FILES` derived from `package-contract.md` §3 and plumbed it through the readiness call as the default expectation. Required shipping paths can no longer be removed without triggering a PkgFiles diagnostic. (P1 #3) `realGit().resolveRef` now peels annotated tags via `^{commit}` so `git rev-parse` returns the commit SHA on both sides of the tag-at-main comparison. Without peeling, an annotated `vX.Y.Z` tag (created via `git tag -a`) returned the tag-object SHA while `main` returned a commit SHA, falsely reporting TAG_NOT_AT_MAIN. The `^{commit}` suffix is a no-op for refs already pointing at a commit (lightweight tags, branches, raw SHAs). Documented the invariant on the `GitInterface` contract. (P2) Release-notes shape check now validates `changelog.exclude.labels` and `changelog.exclude.authors` are arrays. Previously `exclude: {}` passed because only the block's existence was checked, missing the T-V05-003 contract requirement to filter maintenance and bot entries. Tests cover all four fixes (Scenarios 4d, 5d, 5e, 3c plus the existing regression suite). 26 tests pass; full suite green; `npm run verify` ok. Tightened `ExpectedPackage.files` and `expectedPackageFiles` types to `readonly string[]` so the const list satisfies the typecheck. Findings: PR #158 inline comments by chatgpt-codex-connector on commit 13a657d. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two open round-5 P1 findings on dbfca99 closed in this commit (maintainer-directed continuation past the 3-round soft cap). P1 #1 — Parser too strict for legacy tasks.md format ===================================================== Every pre-template `tasks.md: complete` feature in the repo (e.g. `specs/version-0-6-plan/tasks.md`) uses the legacy `### T-V06-001 - Decide steering profile location` shape: no emoji, ASCII hyphen separator, and no `## Task list` / `## Parallelisable batches` / `## Quality gate` subheaders. The previous parser would have hard-stopped on every existing feature. `.claude/agents/issue-breakdown.md` Step 5 + spec "Slicing input" table now require **only** a file with at least one `### T-<AREA>-NNN …` heading and a `**Description:**` bullet underneath it. Everything else is optional with a documented synthesised default: - `## Task list` absent → every `### T-…` heading in the file is a task. - `## Parallelisable batches` absent → synthesise a single batch containing every task in document order (one PR). Surface the synthesis to the conductor so the user confirms / aborts. - `## Quality gate` absent → use the default DoD shipped in `templates/issue-breakdown-pr-body-template.md`. - Per-task `**Definition of done:**` absent → skip the per-task aggregation; the slice DoD falls back to the (possibly default) `## Quality gate`. - Per-task `**Depends on:**` absent → no cross-check. - Per-task `**Satisfies:**` absent → omit from spec lineage. Heading regex relaxed to `^### (T-[A-Z0-9]+-\d{3})(?:\s+([🧪🔨📐📚🚀🪓\s]+?))?\s+[—-]\s+(.+)$` — `<emoji-block>` capture optional, em-dash OR hyphen accepted as separator. May-slice flag still keys off `🪓` presence anywhere in the captured block. Conductor's Step 6 confirm prompt updated to surface whether the slice list came from a real `## Parallelisable batches` section or was synthesised from a legacy `tasks.md`. P1 #2 — Audit / hand-off edits not persisted before cleanup ============================================================ Steps 9 + 10 appended to `specs/<slug>/issue-breakdown-log.md` and `specs/<slug>/workflow-state.md`, then Step 11 deleted the staging dir and exited — leaving the working tree dirty (which conflicts with Step 1's `git status --porcelain` clean-tree gate on the next run) and losing the audit trail unless the operator committed manually. New Step 10.5 cuts a `chore/issue-breakdown-audit-issue-<n>-<runid>` branch from the integration branch, commits the two appends, pushes, and opens a non-draft `chore(issue-breakdown): record run for issue #<n>` PR. The push-deny rules on `main` / `develop` are honoured — the housekeeping branch uses the `chore/` prefix, which the default `.claude/settings.json` allows. If the push is denied (e.g. operator runs against a repo with stricter `chore/*` permissions) the agent surfaces the failure with the local commit SHA so the audit trail can be rescued by hand. Conductor skill, methodology doc, and design spec all updated to reference the new Step 10.5 in the flow diagram + outputs. Refs #183, #184. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
… truth Three new Codex P1s on commit 05d84a9, all real internal-consistency drift between agents/skills/commands and the shared goal-state schema. Fix together so the documented happy paths run end-to-end. current_phase drift (P1 #1): `set-goal` initialises `current_phase: scope` per the shared schema (`scope | observe | orient | decide | act | review | closed`), but several files referenced a non-existent `goal` value or a stale list that excluded `scope`: - /goal:observe accepted `goal | review | observe` — would fail preflight on a freshly signed goal. Now: `scope | review | observe`. - /goal:start said new goals get `current_phase: goal`. Now: `scope`. - /goal:close said amend re-entry sets `current_phase: goal`. Now: `scope` (matching the post-`set-goal` entry state). act_approval drift (P1 #2): The actor, decider, orchestrator, and the Codex iteration workflow all referenced an `act_approval` entry in `goal-state.md`. The shared schema does not define that field. The canonical record of approval lives in the `## Human Approval` section of the decision set in `decisions.md`, which is filled by the `decide` skill at the act gate. - agents/actor.md — pre-flight now reads the Human Approval section of decisions.md as the canonical source, with the orchestrator's `## History` row as the secondary signal that the gate cleared. - agents/goal-orchestrator.md — clarified that Decide owns the Human Approval section; orchestrator appends an act-gate row to `## History` citing the approved decision-set id. - agents/decider.md — clarified the decider does not write the Human Approval section itself; the `decide` skill captures the user's verdict there, then the orchestrator records the `## History` row. - .codex/workflows/goal-iteration.md — same alignment for the Codex side; the Safety rail now references the Human Approval section. Review preflight drift (P1 #3): /goal:review required an `actions/` artifact for every iteration, but the `decide` skill explicitly advances `current_phase: review` with no actions when the act gate produces nothing executable (all rejected, deferred, or `act_gate: never`). That left no-action iterations unable to close. Now /goal:review accepts both: - the post-Act case (actions/ artifact present, the normal path) - the no-action case (`## History` records an `act: skipped` row with reason — `all rejected` / `deferred` / `policy forbids`) `npm run verify` is green locally. https://claude.ai/code/session_01CxFjqxucdBwScjAkMxU83s
Codex P1 #1 (commands/goal/start.md:4) — `allowed-tools` omitted `AskUserQuestion` even though Step 1 (missing slug), Step 2 (existing-goal branch), and Step 3 (session-goal compose check) all need it. Wider sweep: 7 commands use AskUserQuestion across their procedures; all 7 were missing it from `allowed-tools`. Fixed: - commands/set-goal.md - commands/create-goal.md - commands/goal/start.md - commands/goal/amend.md - commands/goal/demo.md - commands/goal/welcome.md - commands/goal/trace.md Codex P1 #2 (.claude-plugin/plugin.json:52) — `capabilities.commands` only registered `commands/goal`, omitting the two top-level session-goal entrypoints. Adopters installing the plugin would not see `/create-goal` or `/set-goal` even though every doc surfaces them. Added explicit paths: - commands/create-goal.md - commands/set-goal.md `bash scripts/check-all.sh`: all 7 checks pass. `check:links` ok. `check-roster` ok (the new manifest entries match disk). https://claude.ai/code/session_01CxFjqxucdBwScjAkMxU83s
…dit + per-command frontmatter check Three P1 items from the wave-9 punch list land together: P1 #1 — README install recipe (README.md §Install): Four concrete install paths replace the prior "copy the folder" wording: (a) Claude Code marketplace (canonical when published), (b) `git subtree` for upstream-tracking adopters, (c) `git submodule` for pinned vendoring, (d) one-shot `cp -r` for fork-and-own. Decision rule appended below the recipes to help adopters pick. The existing `Adopt the entry points` step is preserved. P1 #2 — Required-field enforcement audit (skills/decide/SKILL.md Step 3a): The H-1 research recommendation made `rationale`, `confidence`, `reversible: Y|N` required on every decision proposal. The decider agent §Validation enforces this at first-pass (drops malformed proposals to `## Alternatives Considered`). The skill now enforces at second-pass before opening the act gate: rejects the whole set if any proposal still lacks a required field, surfaces an explicit AskUserQuestion with three options (re-dispatch / drop the malformed / accept-with-acknowledgement). No duplicated enforcement; clean first-pass / second-pass division. P1 #3 — Per-command frontmatter ↔ table consistency check (scripts/check-roster.sh check_8 + automation-spec.md §B2 + scripts/README.md): The §B2 deferral noted in earlier waves is now closed. check_8_command_descriptions extracts each command file's frontmatter `description:` and the corresponding row from commands/goal/README.md's `## Commands` table, then confirms they share at least one substantive keyword (with a stop-word filter for Goal-Loop boilerplate). All 15 /goal:* commands report OK on the current tree — no drift surfaced. automation-spec §B2 status annotation drops the deferral note ("implemented — all surfaces covered"); scripts/README table row enumerates all 8 covered surfaces. `bash scripts/check-all.sh`: all 7 checks pass; check_8 inside check-roster confirms 15/15 commands match their table descriptions. `npm run check:links` and typos clean. https://claude.ai/code/session_01CxFjqxucdBwScjAkMxU83s
…impl-rigor / educator / OODA fidelity Four parallel review subagents (educator / impl-rigor / security / OODA) ran read-only against d63766d. Seven P1 findings consolidated into single-file edits below. Each is load-bearing for either a load-bearing security guarantee, a peer-implementer contract, or the documented audit chain. THREAT-03 (security; data egress) Added `## Export safety` section to `templates/observe-source-datasheet-template.md` with `safe_for_export: false` default-deny. Tightened `skills/export-trace/SKILL.md` boundary so default-deny applies to every source type, not just `inbox | person | dataset`. Pre-wave-9 datasheets (which omit the section) are treated as `safe_for_export: false` — failing open is forbidden. A `feed`, `api`, `repo`, or `document` source can carry attacker-controlled or proprietary content just as easily; the export-safety contract does not vary by source type. THREAT-01 (security; audit-trail keystone) `/goal:demo` now records a demo-seed origin row in `## History` before any phase runs (canonical `outcome: amend`, `artifact: memory/amendments/_demo-seed-origin.md`) and sets `demo_seed: true` in frontmatter. Article III §1 (human goal-gate) is not bypassed silently — the audit trail names the bypass for what it is. `/goal:amend` refuses to clear `demo_seed` silently; promoting a demo to a real goal now requires a recorded amendment with the full goal-gate interview re-run. THREAT-04 + impl-rigor P2-12 (security + spec; criteria laundering) In revive-amend mode, `set-goal` now surfaces an explicit acceptance-criteria diff via `AskUserQuestion` and records the user's `equivalent | weaker | stronger` attestation in the amendment record file. Goal that was `close-abandon`ed cannot be silently re-opened with weaker criteria and re-closed as `close-met` — Article X §3 is preserved through recorded attestation. Fixed iteration-bump semantics: `iteration` is NOT bumped at amend time (the next Observe bumps it, per the canonical rule in `skills/_shared/goal-state.md`). Impl-rigor P1-5 (spec; act-gate parsing contract) Pinned canonical, byte-fixed parsing rule for `## Human Approval` in `templates/decision-template.md`. Act and Actor parse only the `**Approved action ids:**` line — comma-and-space separator, `[a-z0-9-]+` ids, placeholder `<…>` or empty value = no ids, multi-checkbox state forces re-prompt, zero-checkbox + non-empty ids = draft. Closes the act-gate semantic gap two implementers could otherwise interpret differently. Impl-rigor P1-7 (spec; cap-counter contract) Added `## Status enum — canonical boundaries` table to `templates/action-log-template.md` defining `done | partial | stopped | blocked | failed` operationally. Pinned cap-counter rule: `max_failed_acts` counts only `failed`; `stopped` and `blocked` are upstream-fix signals, not act-quality death spirals. Educator #1 + #2 (doc learnability) Promoted `docs/glossary.md` to item #1 in AGENTS.md "Read these first" so the canonical enums are defined before the constitution and method.md reference them. Added `## Canonical enums` consolidator section to `glossary.md` that lists every enum's values + defining doc + users. Replaced Article II §4's forward-reference to undefined enums with a cite to the glossary section. OODA D1 + D8 (Boyd fidelity) Added §"What Boyd's actual diagram looks like" + §"Implicit guidance & control" to `docs/ooda-foundations.md`. Names the seven feedback arrows, the implicit-guidance channel Boyd's late-1996 diagram contains, why the Goal Loop's diagrams in method.md are a deliberate simplification, and how the plugin's conventions function as an implicit-guidance surface. Checks: bash plugin-v2/scripts/check-all.sh → all green.
2 participants
Summary
Adds a mattpocock-style skills layer on top of the v0.1 Spec Kit foundation (PR #1), plus a single doc cataloging the full markdown sink. All net-new — no edits to the v0.1 surface beyond
README.md(adds Skills row + bumps version) andCLAUDE.md(surfacesorchestrateas the recommended entry).What's added
.claude/skills/orchestrate/— the conductorNatural-language entry to the existing 11-stage workflow. Triggers on phrases like "let's start a feature", "drive this end-to-end", "what's next?", or
/orchestrate <goal>.specs/<slug>/workflow-state.mdto detect resume vs. fresh start.AskUserQuestionto capture slug, area code, depth (Standard/Lean/Spike), and opt-in gates./spec:*slash commands per stage — never duplicates their work.AskUserQuestion: continue / pause / re-run with feedback / skip next.workflow-state.md.References split into
PHASES.md(per-stage dispatch context) andRESUME.md(resume protocol) per Pocock's progressive-disclosure pattern.Practice skills (used by stage agents, mattpocock-style)
grill//spec:clarify, analyst, pm, architectdesign-twice/Tasktool (Ousterhout)tracer-bullet/tdd-cycle/record-decision//adr:newCross-cutting sink skills (lazy)
domain-context/docs/CONTEXT.md(orCONTEXT-MAP.md+contexts/<name>.mdfor multi-context projects)ubiquitous-language/docs/UBIQUITOUS_LANGUAGE.md— single canonical glossaryBoth follow Pocock's lazy-creation discipline: file appears on first need, never pre-scaffolded.
docs/sink.md— single source of truth for markdown outputsCatalogs every markdown artifact: workflow-scoped (
specs/<slug>/*.md), cross-cutting (docs/adr/,docs/CONTEXT.md,docs/UBIQUITOUS_LANGUAGE.md), governance (memory/constitution.md,docs/steering/*), and tooling (.claude/{agents,commands,skills}/). Documents ownership, eager vs. lazy, immutability rules, naming conventions, and the read order for any subagent starting a stage..claude/skills/README.mdCatalog of all skills with trigger phrases and authoring guide for new skills.
Design choices
AskUserQuestiononly in the main thread. Subagents cannot ask the user (per Anthropic docs) — the orchestrator does all gating and clarification up front and between stages. This shape is enforced bySKILL.md's constraints section.specs/<slug>/,docs/adr/,docs/steering/,templates/. v0.2 adds the lazyCONTEXT.md/UBIQUITOUS_LANGUAGE.mdfiles (Pocock pattern) and one doc that catalogs the whole sink in one place.SKILL.md≤200 lines; deeper material lives in siblingREFERENCE.mdfiles. Description format follows Pocock's "capability sentence + Use when… sentence" rule.Sources
Built on research into:
grill-me,to-prd,to-issues,domain-model,design-an-interface,improve-codebase-architecture,tddTest plan
.claude/skills/README.md— does the catalog match what's in the folder?.claude/skills/orchestrate/SKILL.md— does the procedure read as a single, complete loop?docs/sink.md— does every artifact path actually exist (or have a clear lazy-creation owner)?tdd-cycle/SKILL.md) — does it stand on its own as guidance for an agent that's never seen it?CLAUDE.mdstill surfaces both entry modes (orchestrate skill + manual/spec:*).https://claude.ai/code/session_01PTc1UHovmBA1Psbd3719KD
Generated by Claude Code