@punks/cli 1.0.7 → 2.0.0-beta.1

package/dist/skills/agnostic/debug/debugging-phase/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: debugging-phase
+description: >-
+  Runs a standalone runtime-evidence debugging phase, or a scoped debugging
+  phase inside delivery when validation or review finds runtime failure. Use
+  when the user reports broken behavior, failing smoke checks, logs,
+  recordings, runtime symptoms, or asks to debug a delivery-scoped failure.
+---
+
+# Debugging Phase
+
+## Contract
+
+- **Role:** public runtime-evidence phase
+- **Entrypoint type:** standalone public skill, or inner phase of `delivery-phase`
+- **Standalone inputs:** user-reported broken behavior, failing smoke checks, logs, recordings, runtime symptoms
+- **Delivery-internal inputs:** `implement-spec` validation failure or `review-phase` runtime failure
+- **Wraps:** `$debug-agent`, optional readonly `$parallel-research`, bounded fixes, focused tests or scenario reruns, review
+- **Owns:** evidence matrices, cited log references, hypothesis status, fix verification
+- **Exit conditions:** bug fixed, concrete blocker proven, or scope proven to require a spec/delivery goal
+
+## Use When
+
+- Runtime behavior is broken, flaky, slow, or inconsistent.
+- Smoke checks, browser checks, CLI checks, recordings, or logs show a failure.
+- A delivery run hits a runtime failure during validation or review.
+- The user asks for evidence-backed debugging instead of code-only inspection.
+
+## Do Not Use When
+
+- The work is pure planning, requirements discovery, or design.
+- The failure is already proven and only needs implementation inside an active spec plan.
+- The fix would require broad product scope, architecture, or acceptance changes; exit to `create-spec`, `create-plan`, or a delivery goal instead.
+- The request is only static code review with no runtime symptom.
+
+## Workflow
+
+1. **Classify entry.**
+   - Standalone: record the broken behavior, artifact links/paths, reproduction command or manual scenario, expected behavior, and observed behavior.
+   - Delivery-internal: cite the validation or review failure that triggered debugging and the delivery scope it belongs to.
+2. **Set bounds.**
+   - Define owned files, systems, and scenarios.
+   - For delivery-internal debugging, patch only inside the active delivery scope.
+   - If the evidence points outside that scope, record debt or open a separate debugging/debt goal.
+3. **Run `$debug-agent`.**
+   - Build 3-5 hypotheses.
+   - Instrument or inspect with runtime evidence.
+   - Keep an evidence matrix with each hypothesis marked `confirmed`, `rejected`, or `inconclusive`.
+   - Cite log lines, recordings, commands, test output, or scenario evidence for every status.
+4. **Optionally run readonly `$parallel-research`.**
+   - Use for independent hypotheses, unfamiliar subsystems, logs, docs, or prior-art inspection.
+   - Synthesize findings before fixing.
+5. **Fix only proven causes.**
+   - Make the smallest bounded patch that addresses confirmed evidence.
+   - Remove speculative changes from rejected hypotheses.
+   - Keep debug instrumentation until post-fix evidence proves success, unless the user explicitly asks for cleanup.
+6. **Verify.**
+   - Rerun the failing smoke check, focused test, browser path, CLI command, or manual scenario.
+   - Compare before/after evidence.
+   - Run review appropriate to the touched scope.
+7. **Exit.**
+   - Fixed: report cause, patch, verification, and residual risk.
+   - Blocked: report the concrete blocker and the missing artifact/access/action.
+   - Out of scope: report why this needs a spec/delivery goal or debt issue.
+
+## Parallel Rules
+
+`debugging-phase` may run with `parallel: true` or `parallel: false`.
+
+- `parallel: false`: one thread owns hypotheses, instrumentation, fix, verification, and review.
+- `parallel: true`: fan out readonly research for independent hypotheses only.
+- Disjoint worker fixes are allowed only after the cause is proven and file ownership is explicit.
+- Never let parallel workers make speculative fixes against unproven hypotheses.
+- Merge worker findings into one evidence matrix before deciding on a patch.
+- In delivery-internal mode, parallel workers must stay inside the delivery scope unless assigned readonly investigation.
+
+## Output Contract
+
+Return a concise debugging report with:
+
+- **Mode:** standalone or delivery-internal; `parallel: true|false`
+- **Input artifacts:** reports, logs, recordings, checks, or symptoms used
+- **Evidence matrix:** hypotheses, status, and cited evidence
+- **Root cause:** confirmed cause or why none is proven
+- **Changes:** bounded patch summary, or none if blocked/out of scope
+- **Verification:** commands/scenarios rerun and result
+- **Exit:** fixed, blocked, or escalated to spec/delivery/debt

package/dist/skills/agnostic/docs/docs-ingest-phase/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: docs-ingest-phase
+description: Ingest specs into the wiki source layer, project wiki/project pages into Fumadocs routes, and keep repo docs accurate. Use when a spec is ready for domain capture, when apps/wiki content or Fumadocs navigation changes, or when code changes alter architecture, setup, contracts, or operator workflow.
+---
+
+# Docs Ingest Phase
+
+## Contract
+
+- **Role:** higher-order ingest and repo-docs phase
+- **Entrypoint type:** public phase entrypoint
+- **Upstream:** reviewed or implemented spec folder, or concrete docs-affecting code changes
+- **Delegates to:** internal flow-writing phase, internal concept-writing phase, Fumadocs projection
+- **Downstream:** synced wiki indexes, ingest metadata, wiki log, routed Fumadocs pages/meta, and required `docs/` updates
+- **Entry conditions:** resolved spec folder for ingest work, or a concrete docs-affecting code change
+- **Stop conditions:** ingest bookkeeping complete, required docs updates complete, failures reported honestly
+
+## Use When
+
+- A reviewed or implemented spec folder should become durable domain knowledge.
+- `apps/wiki` source content, Fumadocs navigation, `meta.json`, or routed pages change.
+- Code changes alter architecture, setup, contracts, decisions, runbooks, or operator workflow.
+- `delivery-phase` reaches `$docs-ingest-phase` and docs-affecting changes exist.
+
+## Do Not Use When
+
+- The work is still requirements discovery, planning, coding, or review.
+- The target spec is already marked `ingested: true`; report a no-op.
+- The requested docs would document speculative future behavior as current truth.
+- The task would duplicate large specs/plans/source pages into routed MDX instead of summarizing and linking.
+
+## Quick Start
+
+1. Resolve `<wiki-root>`:
+   - monorepo: `apps/wiki`
+   - single-repo: `wiki`
+2. Read `<wiki-root>/AGENTS.md` before touching wiki content.
+3. If ingesting a spec, read [references/wiki-ingest.md](references/wiki-ingest.md).
+4. If updating routed docs, read [references/fumadocs-routing.md](references/fumadocs-routing.md).
+5. If updating root `docs/`, read [references/repo-docs.md](references/repo-docs.md).
+6. Finish by reporting written pages, metadata changes, docs updates, validation run, and any no-op reason.
+
+## Wiki Ingest Pipeline
+
+Run this order exactly:
+
+```text
+docs-ingest-phase
+  -> flow-writing phase
+  -> concept-writing phase
+  -> ingest bookkeeping
+  -> Fumadocs projection
+```
+
+Why: concept pages can cross-link flow pages, so flows must exist first.
+
+## Fumadocs Routing
+
+Keep the private Fumadocs app discoverable:
+
+- `/docs/wiki` renders product/domain knowledge: usage, concepts, theory, flows, glossary, and concept/flow ingest output.
+- `/docs/project` renders internal project operations: specs, plans, implementation notes, maintenance logs, decisions, repo guidance, runbooks, and useful management context.
+
+Do not create a second wiki or separate content-owner layer. `apps/wiki` owns canonical source content and rendered Fumadocs pages.
+
+## Output Contract
+
+Always report:
+
+- source spec or docs-affecting change processed
+- flows written or skipped
+- concepts written or skipped
+- source frontmatter/bookkeeping updates
+- Fumadocs routed pages and `meta.json` updates
+- root `docs/` updates, if any
+- validation commands run
+- no-op reasons or blockers
+
+## Never Do
+
+- Leave new or moved routed pages out of Fumadocs `meta.json`.
+- Strip or omit `surface` / `permission` frontmatter from routed pages.
+- Proceed to concept writing after a flow write fails.
+- Create `docs/prd`, `docs/dev`, roadmap, sprint, or backlog-mirror folders.
+- Put agent task instructions inside human-facing docs pages.
+- Leave docs orphaned from `docs/README.md` after adding or renaming them.
+- Duplicate content between `<wiki-root>/domains/` and `docs/reference/domains/`.

package/dist/skills/agnostic/docs/docs-ingest-phase/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Docs Ingest Phase"
+  short_description: "Wiki ingest plus repo docs maintenance"
+  default_prompt: "Use $docs-ingest-phase to own the wiki ingest pipeline, then keep docs/ human-facing and implementation-grounded when code changes affect durable knowledge."

package/dist/skills/agnostic/docs/{docs-maintenance → docs-ingest-phase}/references/concept-pages.md

@@ -1,6 +1,6 @@
 # Concept Pages
 
-Use this reference during Step 6 of `docs-maintenance`.
+Use this reference during Step 6 of `docs-ingest-phase`.
 
 ## Input expansion
 

package/dist/skills/agnostic/docs/{docs-maintenance → docs-ingest-phase}/references/flow-pages.md

@@ -1,6 +1,6 @@
 # Flow Pages
 
-Use this reference during Step 4 of `docs-maintenance`.
+Use this reference during Step 4 of `docs-ingest-phase`.
 
 ## Output contract
 

package/dist/skills/agnostic/docs/docs-ingest-phase/references/fumadocs-routing.md

@@ -0,0 +1,88 @@
+# Fumadocs Routing
+
+Use this reference during Step 10 of `docs-ingest-phase`.
+
+## Source And Projection
+
+`apps/wiki` is both the private Fumadocs app and the canonical wiki source owner. Do not create another wiki, another content-owner layer, or a mirrored docs tree outside this app.
+
+Canonical source content may remain in:
+
+- `apps/wiki/domains`
+- `apps/wiki/specs`
+- `apps/wiki/raw`
+- `apps/wiki/index.md`
+- `apps/wiki/log.md`
+
+Rendered/discoverable pages live under:
+
+- `apps/wiki/content/docs/wiki`
+- `apps/wiki/content/docs/project`
+
+The routed pages are a projection layer. They may summarize, curate, and point back to canonical source files. They should not duplicate large specs, plans, implementation notes, runbooks, or source pages.
+
+## Route Boundaries
+
+Use `/docs/wiki` for product/domain knowledge:
+
+- usage model
+- concepts
+- theory
+- flows
+- glossary
+- docs-ingest-phase concept/flow ingest output
+
+Use `/docs/project` for internal project operations:
+
+- specs
+- plans
+- implementation notes
+- maintenance logs
+- decisions
+- repo guidance
+- operator/project runbooks
+- useful Linear/grill-derived management context
+
+Docs ingest concepts and flows are abstract/domain-theory outputs. The Fumadocs projection makes those outputs navigable.
+
+## Fumadocs Mechanics
+
+Fumadocs uses file paths to determine route slugs. Examples:
+
+- `content/docs/wiki/index.mdx` -> `/docs/wiki`
+- `content/docs/wiki/cli/index.mdx` -> `/docs/wiki/cli`
+- `content/docs/project/specs/index.mdx` -> `/docs/project/specs`
+
+Each folder with an explicit `meta.json` `pages` array must list every page or child folder that should appear in the page tree. Update `meta.json` whenever pages are added, moved, or removed.
+
+Use root folders for the two main surfaces:
+
+```json
+{
+  "title": "Wiki",
+  "root": true
+}
+```
+
+```json
+{
+  "title": "Project",
+  "root": true
+}
+```
+
+## Access Frontmatter
+
+Preserve access-control frontmatter on routed pages:
+
+```yaml
+surface: wiki
+permission: internal
+```
+
+```yaml
+surface: project
+permission: project
+```
+
+Do not implement full auth unless the repo already has the required auth primitives. When auth exists, prefer a small Fumadocs loader-level filter so restricted files are removed from the input source before page tree/search generation.

package/dist/skills/agnostic/docs/docs-ingest-phase/references/repo-docs.md

@@ -0,0 +1,38 @@
+# Repo Docs
+
+Use this reference when code or workflow changes require root `docs/` maintenance.
+
+## Scope
+
+Update root `docs/` when a change alters:
+
+- architecture
+- setup
+- contracts
+- decisions
+- runbooks
+- non-obvious operator-facing behavior
+
+Do not let repo-doc work displace required wiki ingest. If both apply, complete ingest bookkeeping and then update root docs.
+
+## Workflow
+
+1. Read `docs/README.md`.
+2. Read the nearest affected section README before editing.
+3. Prefer editing an existing leaf doc over creating a new one.
+4. When a doc is added, removed, or renamed, update `docs/README.md` and the nearest section README in the same task.
+5. Record repo-wide behavior changes in `docs/architecture/decisions/` when that directory exists.
+
+## Route By Owned Behavior
+
+- Backend/runtime surface -> `docs/reference/domains/backend-effect-sql.md` or `docs/runbooks/`
+- Auth/user-management -> `docs/reference/domains/user-management.md`
+- Frontend/app structure -> `docs/reference/domains/frontend-application-structure.md`
+- AI workflow/agent infrastructure -> `docs/runbooks/subagent-templates.md` or the relevant harness runbook
+
+## Rules
+
+- Document implemented reality, not speculative future state.
+- Keep human docs human-facing; do not paste agent task instructions into them.
+- Keep indexes current when adding, removing, or renaming docs.
+- Link to source artifacts instead of duplicating large specs, plans, or implementation notes.

package/dist/skills/agnostic/docs/docs-ingest-phase/references/wiki-ingest.md

@@ -0,0 +1,131 @@
+# Wiki Ingest
+
+Use this reference when `docs-ingest-phase` receives a spec folder, domain/spec pair, or explicit `SPEC.md`.
+
+## Inputs
+
+Accept any of:
+
+- `<wiki-root>/specs/<domain>/<spec>/`
+- a domain name plus spec name
+- an explicit `SPEC.md` path
+
+Resolve to a full spec folder before continuing. If ambiguous, ask only for the missing folder.
+
+## Guard
+
+1. Read `SPEC.md`. Stop if missing.
+2. Check `SPEC.md` frontmatter for `ingested: true`; if set, exit with a clear no-op.
+3. Verify `domain:` exists in frontmatter.
+4. Verify `<wiki-root>/domains/<domain>/` exists with a `<domain>.md` index file. If missing, stop and scaffold the domain structure first.
+
+## Source Read
+
+Read in order:
+
+1. `SPEC.md` — mandatory
+2. `IMPLEMENTATION-NOTES.md` — optional
+
+If implementation notes exist and lack frontmatter, add:
+
+```yaml
+---
+domain: <domain from SPEC.md>
+type: implementation-notes
+spec: <spec id from SPEC.md>
+links:
+  - "[[specs/<domain>/<spec>/SPEC]]"
+ingested: false
+last_ingested: null
+created: <today>
+updated: <today>
+---
+```
+
+When notes exist, generated flows and concepts should be `status: implemented`. Without notes, they are `status: proposed`.
+
+## Extract Flows
+
+A flow exists when the spec describes a sequence of user or system actions with a defined start, steps, and end outcome.
+
+Look for:
+
+- multi-step acceptance criteria
+- explicit journeys or process descriptions
+- conditional chains across acceptance criteria
+- sections titled Flow, Process, Journey, or similar
+
+For each flow, extract:
+
+- descriptive flow name
+- trigger
+- actors
+- ordered steps and decision points
+- terminal outcome
+- implementation deviations, surprises, or blocked steps when notes exist
+
+If no multi-step sequence exists, record the absence and skip flow writing.
+
+## Write Flow Pages
+
+Read [flow-pages.md](flow-pages.md) and apply it to every extracted flow.
+
+Wait for all flow pages to complete before concept writing. If any flow write fails, stop and report the failure so the run can resume cleanly.
+
+## Extract Concepts
+
+A concept exists when the spec names a domain entity or term with defined attributes, invariants, or bounded scope.
+
+Look for:
+
+- fields listed in acceptance criteria
+- explicit data model or entity sections
+- recurring nouns with their own attributes or rules
+- enum sets representing bounded domain state
+- entities referenced through wikilinks
+
+Group related fields under one owning entity. Do not create a concept per field when one domain entity owns them.
+
+## Write Concept Pages
+
+Read [concept-pages.md](concept-pages.md) and apply it to every extracted concept.
+
+Concept pages may cross-link flow pages, which is why flow writing must complete first.
+
+## Bookkeeping
+
+Update `SPEC.md` frontmatter:
+
+```yaml
+ingested: true
+last_ingested: YYYY-MM-DD
+```
+
+If `IMPLEMENTATION-NOTES.md` exists, update:
+
+```yaml
+ingested: true
+last_ingested: YYYY-MM-DD
+```
+
+Also populate its `links` array with the SPEC link plus every flow and concept page written in this ingest.
+
+Append to `<wiki-root>/log.md` and cap the log at 50 entries:
+
+```md
+## [YYYY-MM-DD] ingest | <spec title>
+
+- Source: [[specs/<domain>/<spec>/SPEC]]
+- Flows written: <count>
+- Concepts written: <count>
+```
+
+If new pages were created, update Concepts and Flows counts in `<wiki-root>/index.md`.
+
+## Resumability
+
+Output pages are checkpoints:
+
+- existing flow pages with `ingested: true` can be skipped
+- missing expected flow pages should be rewritten before concepts
+- existing concept pages with `ingested: true` can be skipped

package/dist/skills/agnostic/planning/create-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: create-plan
-description: Creates execution-ready `PLAN.md` artifacts by explicitly wrapping `grill-me`, `swarm-planner`, and `tdd` into one planning run. Use when work must be decomposed before coding, especially for reviewed spec workflows, multi-agent execution, branch-scoped delivery, or any task that needs explicit dependencies, backlog items, review gates, and per-task RED targets.
+description: Creates execution-ready `PLAN.md` artifacts by explicitly wrapping `grill-me`, `parallel-research`, `swarm-planner`, and `tdd` into one planning run. Use when work must be decomposed before coding, especially for reviewed spec workflows, multi-agent execution, branch-scoped delivery, or any task that needs explicit dependencies, backlog items, review gates, and per-task RED targets.
 ---
 
 # Create Plan
@@ -10,7 +10,7 @@ description: Creates execution-ready `PLAN.md` artifacts by explicitly wrapping
 - **Role:** higher-order planning orchestrator
 - **Entrypoint type:** public entrypoint
 - **Upstream:** approved `SPEC.md` or explicit planning request
-- **Delegates to:** `$grill-me`, `$swarm-planner`, `$tdd`
+- **Delegates to:** `$grill-me`, `$parallel-research`, `$swarm-planner`, `$tdd`
 - **Downstream:** execution-ready `PLAN.md` for `implement-spec`
 - **Entry conditions:** scope is clear enough to plan; stop if required planning inputs or tools are missing
 - **Stop conditions:** `PLAN.md` and backlog sync are complete; no implementation started
@@ -18,6 +18,7 @@ description: Creates execution-ready `PLAN.md` artifacts by explicitly wrapping
 ## Required Inner Skills
 
 - MUST use `$grill-me`
+- MUST consider `$parallel-research` for readonly planning discovery
 - MUST use `$swarm-planner`
 - MUST use `$tdd`
 
@@ -30,12 +31,13 @@ Create a plan first. Never implement code in this skill.
 3. Read `references/grill-phase.md` and run `$grill-me` as an explicit inner phase.
 4. Update a running decision ledger after every answer so the user never has to reconstruct state from memory.
 5. Insert a synthesis checkpoint before the thread gets noisy, then continue only if more ambiguity reduction is still needed.
-6. Research with `opensrc path <package>` or `opensrc path <owner>/<repo>` plus primary-source web docs when current behavior matters.
-7. Locate scoped `AGENTS.md` files for every planned task path, extract `Primary skills here` lists, and load the relevant skill guidance before finalizing task design.
-8. Read `references/planner-phase.md` and run `$swarm-planner` as an explicit inner phase.
-9. Read `references/tdd-phase.md` and run `$tdd` as an explicit inner phase.
-10. Read `references/backlog-sync.md` and sync backlog at epic/story level, not one item per plan task.
-11. Read `references/stop-conditions.md` and stop exactly there.
+6. If readonly discovery has independent code paths, specs, backlog items, external docs, or hypotheses, read and use `$parallel-research` before final task synthesis.
+7. Research with `opensrc path <package>` or `opensrc path <owner>/<repo>` plus primary-source web docs when current behavior matters.
+8. Locate scoped `AGENTS.md` files for every planned task path, extract `Primary skills here` lists, and load the relevant skill guidance before finalizing task design.
+9. Read `references/planner-phase.md` and run `$swarm-planner` as an explicit inner phase.
+10. Read `references/tdd-phase.md` and run `$tdd` as an explicit inner phase.
+11. Read `references/backlog-sync.md` and sync backlog at epic/story level, not one item per plan task.
+12. Read `references/stop-conditions.md` and stop exactly there.
 
 ## Workflows
 
@@ -44,7 +46,7 @@ Create a plan first. Never implement code in this skill.
 1. Derive host, owner, tracker, and scope from repo state instead of assuming them.
 2. Ask only for missing high-impact inputs such as scope, goal, or backlog target.
 3. Every plan-shaping question must use the exact block: `Decision`, `Recommendation`, `Question`, `Why it matters`.
-4. Keep `$grill-me`, `$swarm-planner`, and `$tdd` as visible required inner phases of one planning run.
+4. Keep `$grill-me`, `$parallel-research`, `$swarm-planner`, and `$tdd` as visible inner phases of one planning run; record when `$parallel-research` is used or intentionally skipped because the work is not split-friendly.
 5. Resolve each task's scoped guidance from root `AGENTS.md` down to the nearest `AGENTS.md` for its `location`.
 6. Use each task's required skill guidance while shaping its scope, dependencies, validation, RED target, and review mode; do not merely list skills after the plan is written.
 7. Assign each task the exact existing skills required by those scoped `Primary skills here` lists, merging all scopes for cross-directory tasks.

package/dist/skills/agnostic/planning/create-spec/SKILL.md

@@ -10,7 +10,7 @@ description: Create a SPEC.md file for a new feature, product, or system using t
 - **Role:** higher-order spec authoring skill
 - **Entrypoint type:** public entrypoint
 - **Upstream:** new idea, feature request, epic/capability issue, or problem statement
-- **Delegates to:** `$requirements-grill` when discovery leaves meaningful spec-affecting unknowns; `$write-backlog` when grill outcomes change epic/story scope
+- **Delegates to:** `$parallel-research` for split-friendly readonly discovery; `$requirements-grill` when discovery leaves meaningful spec-affecting unknowns; `$write-backlog` when grill outcomes change epic/story scope
 - **Downstream:** reviewed `SPEC.md`, then usually `create-plan` or `implement-spec`
 - **Entry conditions:** wiki domain can be resolved, or the user creates one first with `create-wiki-domain`
 - **Stop conditions:** `SPEC.md`, wiki index, and wiki log are updated, then wait for user review
@@ -25,16 +25,17 @@ The output lives at `apps/wiki/specs/<domain>/<folder-name>/SPEC.md`.
 
 1. Read `apps/wiki/AGENTS.md` first. Stop if the wiki is not bootstrapped.
 2. Read `references/discovery.md` and orient yourself in the right wiki domain before asking questions.
-3. If backlog context exists, read the parent epic and every child story before asking questions.
-4. If the user did not provide a concrete request, ask for a rough description first.
-5. Read `references/questioning.md` and ask only the lightweight clarifying questions needed to identify whether a grill phase is required.
-6. If draft `Open Questions` would affect spec trust, read `references/grill-phase.md` and run a bounded `$requirements-grill` phase before writing.
-7. If the grill changes accepted scope, child stories, deferred scope, or story order, read `references/backlog-sync.md` and run `$write-backlog` to sync the backlog automatically.
-8. Read `references/folder-naming.md` to resolve the domain and spec folder path.
-9. Read `assets/SPEC-TEMPLATE.md` and write the spec.
-10. Read `references/spec-quality-bar.md` before saving.
-11. Read `references/wiki-bookkeeping.md` to update `index.md`, `<domain>-specs.md`, and `log.md`.
-12. Read `references/handoff.md` to choose the next-step recommendation and stop after user review.
+3. When discovery spans independent code paths, docs, backlog items, prior specs, or hypotheses, read and use `$parallel-research` for readonly sidecar coverage before synthesizing.
+4. If backlog context exists, read the parent epic and every child story before asking questions.
+5. If the user did not provide a concrete request, ask for a rough description first.
+6. Read `references/questioning.md` and ask only the lightweight clarifying questions needed to identify whether a grill phase is required.
+7. If draft `Open Questions` would affect spec trust, read `references/grill-phase.md` and run a bounded `$requirements-grill` phase before writing.
+8. If the grill changes accepted scope, child stories, deferred scope, or story order, read `references/backlog-sync.md` and run `$write-backlog` to sync the backlog automatically.
+9. Read `references/folder-naming.md` to resolve the domain and spec folder path.
+10. Read `assets/SPEC-TEMPLATE.md` and write the spec.
+11. Read `references/spec-quality-bar.md` before saving.
+12. Read `references/wiki-bookkeeping.md` to update `index.md`, `<domain>-specs.md`, and `log.md`.
+13. Read `references/handoff.md` to choose the next-step recommendation and stop after user review.
 
 ## Workflow
 
@@ -42,13 +43,14 @@ The output lives at `apps/wiki/specs/<domain>/<folder-name>/SPEC.md`.
 
 1. Build orientation first; do not jump straight into writing.
 2. Ask only enough to make the spec crisp, testable, and bounded.
-3. When an epic has child stories, harvest and preserve each story's requirements before drafting.
-4. Use `$requirements-grill` for meaningful spec-affecting unknowns; do not replace that phase with ad hoc `Open Questions` prompts.
-5. After a grill phase, use `$write-backlog` automatically when accepted decisions imply backlog changes.
-6. Keep the spec free of implementation detail.
-7. Use the template structure exactly, then remove all template scaffolding.
-8. Update wiki bookkeeping in the same run.
-9. Stop after presenting the spec and the recommended next step.
+3. Use `$parallel-research` when readonly orientation can be split cleanly across independent evidence sources; keep synthesis and spec decisions local.
+4. When an epic has child stories, harvest and preserve each story's requirements before drafting.
+5. Use `$requirements-grill` for meaningful spec-affecting unknowns; do not replace that phase with ad hoc `Open Questions` prompts.
+6. After a grill phase, use `$write-backlog` automatically when accepted decisions imply backlog changes.
+7. Keep the spec free of implementation detail.
+8. Use the template structure exactly, then remove all template scaffolding.
+9. Update wiki bookkeeping in the same run.
+10. Stop after presenting the spec and the recommended next step.
 
 ## Advanced features
 

package/dist/skills/agnostic/planning/delivery-phase/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: delivery-phase
+description: Goal-compatible workhorse wrapper for scoped execution from specification through delivery closeout. Use when a user asks to deliver a scoped goal end to end, especially when work should flow through create-spec, create-plan, implement-spec, review, optional debugging, and docs-ingest-phase.
+---
+
+# Delivery Phase
+
+`delivery-phase` owns scoped execution until the goal is either done or honestly
+blocked. It preserves the workflow chain instead of compressing implementation
+into a single coding pass.
+
+## Use When
+
+- The user asks to deliver, execute, finish, close, or carry a scoped goal end to end.
+- A goal needs spec, plan, implementation, review, validation, and docs handling in one wrapper.
+- Existing `SPEC.md` or `PLAN.md` artifacts may be reused, but delivery still needs closeout.
+- The user chooses `parallel: true` or `parallel: false` for implementation mode.
+
+## Do Not Use When
+
+- The request is only requirements discovery, planning, review, debugging, or docs ingest.
+- The scope is too vague to name a goal, issue, spec folder, or bounded change.
+- The user explicitly asks not to code or wants a plan/spec only.
+- Runtime evidence points to a broad bug outside the active delivery scope; create a separate debugging or debt goal.
+
+## Contract
+
+- **Role:** public scoped-delivery orchestrator
+- **Wraps:** `$create-spec` -> `$create-plan` -> `$implement-spec` -> `$review-phase` -> optional `$debugging-phase` -> `$docs-ingest-phase`
+- **Owns:** goal bounds, mode choice, validation, review follow-through, docs ingest outcome, debt capture, blocker reporting
+- **Stop condition:** implemented, reviewed, validated, docs ingest handled, debt captured, or concrete blocker reported
+
+## Workflow
+
+1. **Frame the delivery goal.**
+   - Identify the bounded goal, issue, spec folder, branch, and ownership constraints.
+   - State assumptions, known artifacts, and the validation surface.
+   - If scope is ambiguous, ask before entering the chain.
+2. **Create or reuse the spec.**
+   - If no reviewed `SPEC.md` exists, run `$create-spec`.
+   - If a spec exists, verify it matches the requested scope before continuing.
+3. **Create or reuse the plan.**
+   - If no execution-ready `PLAN.md` exists, run `$create-plan`.
+   - If a plan exists, verify dependencies, validation gates, assigned skills, and review mode.
+4. **Implement the plan.**
+   - Run `$implement-spec` with the selected `parallel: true|false` mode.
+   - Keep implementation inside the delivery scope and update required notes/debt artifacts.
+5. **Review every coding run.**
+   - Run `$review-phase` after `implement-spec` even when tests pass.
+   - Fix in-scope blocking findings before final closeout.
+6. **Debug only runtime-evidence failures.**
+   - Run `$debugging-phase` only when validation or review produces runtime evidence of a bug.
+   - Patch only inside delivery scope.
+   - If the bug is broader, capture tech debt or open a separate debugging/debt goal.
+7. **Run docs ingest.**
+   - Run `$docs-ingest-phase` when implementation changed product behavior, architecture, setup, operator workflow, docs contracts, or spec domain knowledge.
+   - If docs ingest is not needed, record the explicit no-op reason in the final report or delivery notes.
+8. **Close out.**
+   - Report implementation, review result, validation, docs ingest outcome, debt captured, and remaining blockers.
+
+## Mode And Parallel Rules
+
+- Preserve `parallel: true|false` through `$implement-spec`.
+- If the user chose a mode, honor it.
+- If not, choose the smallest safe mode:
+  - `parallel: false` for tightly coupled work, unclear ownership, or small changes.
+  - `parallel: true` only when the plan has independent waves and disjoint write scopes.
+- Do not let parallel workers expand the delivery scope.
+- Optional `$debugging-phase` may use parallel readonly hypothesis research, but speculative parallel fixes are not allowed.
+
+## Output Contract
+
+Return a concise delivery report with:
+
+- **Goal:** scoped outcome delivered or blocker encountered
+- **Mode:** `parallel: true|false` and why
+- **Artifacts:** spec, plan, implementation notes, debt, docs, or tracker links touched
+- **Review:** mandatory `$review-phase` result and remaining findings
+- **Debugging:** skipped with reason, or `$debugging-phase` evidence and result
+- **Validation:** commands, browser checks, smoke tests, or manual scenarios run
+- **Docs ingest:** `$docs-ingest-phase` run, or explicit no-op reason
+- **Exit:** done, blocked, or split into follow-up debt/debugging goal