akili-specs 2.1.0

package/docs/cli.md

@@ -0,0 +1,187 @@
+# CLI Reference
+
+The `akili` CLI installs the AKILI command prompts, skills, and helper resources into Claude Code, OpenCode, Google Antigravity, or multiple tools.
+
+## Install
+
+### Interactive Mode (Recommended)
+
+Run the CLI without arguments or use the `init` command to launch an interactive wizard. It will guide you through selecting the target tools and choosing between global or local installation:
+
+```bash
+pnpm dlx akili-specs
+# or
+akili init
+```
+
+### Manual Installation
+
+Run directly from npm:
+
+```bash
+pnpm dlx akili-specs install --tool claude
+pnpm dlx akili-specs install --tool opencode
+pnpm dlx akili-specs install --tool antigravity
+pnpm dlx akili-specs install --tool both
+pnpm dlx akili-specs install --tool all
+```
+
+Claude is the default target:
+
+```bash
+pnpm dlx akili-specs install
+```
+
+Use a persistent global install if preferred:
+
+```bash
+pnpm add -g akili-specs
+akili install --tool all
+```
+
+To install directly into the local project workspace instead of globally, use the `--local` flag:
+
+```bash
+akili install --tool both --local
+```
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `akili init` | Interactive setup wizard for installation |
+| `akili install` | Install commands, skills, and helper resources |
+| `akili update` | Reinstall packaged commands, skills, and helper resources |
+| `akili list` | List packaged commands, skills, and helper resources |
+| `akili doctor` | Check whether expected files are installed |
+| `akili help` | Show help |
+
+## Options
+
+| Option | Applies To | Purpose |
+|---|---|---|
+| `--tool claude` | install, update, doctor | Target Claude Code config |
+| `--tool opencode` | install, update, doctor | Target OpenCode config |
+| `--tool antigravity` | install, update, doctor | Target Google Antigravity config |
+| `--tool both` | install, update, doctor | Target Claude and OpenCode |
+| `--tool all` | install, update, doctor | Target Claude, OpenCode, and Antigravity |
+| `--target <path>` | single-tool install/update/doctor | Override the selected tool target directory |
+| `--claude-target <path>` | multiple tools | Override Claude target directory |
+| `--opencode-target <path>` | multiple tools | Override OpenCode target directory |
+| `--antigravity-target <path>` | multiple tools | Override Antigravity target directory |
+| `--local`, `-l` | install, update, doctor | Target the current project directory (e.g., `./.claude`) instead of the global home directory |
+| `--force` | install, update | Overwrite existing files |
+| `--dry-run` | install, update | Show planned writes without writing files |
+| `--commands-only` | install, update, doctor | Only install or check commands |
+| `--skills-only` | install, update, doctor | Only install or check skills |
+| `--fix` | doctor | Automatically repair and copy missing files |
+
+`--commands-only` and `--skills-only` are mutually exclusive.
+
+## Install Targets
+
+Default targets:
+
+```text
+Claude:      ~/.claude
+OpenCode:    ~/.config/opencode
+Antigravity: ~/.gemini
+```
+
+Claude install layout:
+
+```text
+~/.claude/commands/
+~/.claude/skills/
+~/.claude/akili/scripts/
+~/.claude/akili/templates/      (leader.md, implementer.md, reviewer.md — used by /akili-constitution to scaffold project .agents/)
+~/.claude/akili/.mcp.json.example
+```
+
+OpenCode install layout:
+
+```text
+~/.config/opencode/commands/
+~/.config/opencode/skills/
+~/.config/opencode/akili/scripts/
+~/.config/opencode/akili/templates/
+~/.config/opencode/akili/.mcp.json.example
+```
+
+Antigravity install layout:
+
+```text
+~/.gemini/antigravity/global_workflows/  (custom commands mapped as global workflows)
+~/.gemini/config/skills/                 (skills mapped as global skills)
+~/.gemini/config/akili/scripts/         (scripts mapped as config resources)
+~/.gemini/config/akili/templates/       (multi-agent harness templates: leader, implementer, reviewer)
+~/.gemini/config/akili/.mcp.json.example
+```
+
+Restart Claude Code, OpenCode, or Google Antigravity after install/update so running sessions load new commands and skills.
+
+## Safety Rules
+
+- Existing files are skipped by default.
+- Use `--force` to overwrite old installed files.
+- Use `--dry-run` before changing custom targets.
+- `update` is intentionally the same safe copy behavior as `install` unless `--force` is provided.
+
+## Examples
+
+Preview a three-tool install:
+
+```bash
+akili install --tool all --dry-run
+```
+
+Install Claude commands into a local project folder:
+
+```bash
+akili install --tool claude --target ./.claude
+```
+
+Install both tools into custom directories:
+
+```bash
+akili install --tool both --claude-target ./.claude --opencode-target ./.opencode
+```
+
+Update Antigravity skills only:
+
+```bash
+akili update --tool antigravity --skills-only --force
+```
+
+Check all installs:
+
+```bash
+akili doctor --tool all
+```
+
+## Packaged Resources
+
+The CLI installs helper resources under the target `akili/` directory:
+
+| Resource | Purpose |
+|---|---|
+| `scripts/gsc_verify.py` | Google Site Verification helper used by `/akili-seo` |
+| `scripts/parse_tests.js` | Jest/Vitest JSON test-output parser used by `/akili-test` to generate the requirement-to-test matrix |
+| `templates/leader.md` | Default Leader (Orchestrator) persona for the multi-agent harness — copied into project `.agents/` by `/akili-constitution` |
+| `templates/implementer.md` | Default Implementer persona for the multi-agent harness |
+| `templates/reviewer.md` | Default Reviewer persona for the multi-agent harness |
+| `.mcp.json.example` | Example MCP config for the Google Search Console MCP server |
+
+## Troubleshooting
+
+If commands do not appear in your AI tool:
+
+- Run `akili doctor --tool <claude|opencode|antigravity|both|all>`.
+- Restart Claude Code, OpenCode, or Google Antigravity.
+- Confirm the target directory is the one your tool reads.
+- Re-run with `--force` if older files should be replaced.
+
+If helper resources are missing:
+
+- Run `akili doctor --tool <target>` without `--commands-only` or `--skills-only`.
+- Re-run `akili install --tool <target> --force`.

package/docs/commands/README.md

@@ -0,0 +1,43 @@
+# Command Reference
+
+AKILI commands are installed as slash-command prompts for Claude Code and OpenCode. The installable source files live in `.claude/commands/`.
+
+## Command Map
+
+| Command | Use When | Main Output |
+|---|---|---|
+| [`/akili-constitution`](akili-constitution.md) | Starting a repo or repairing weak project context | Project baseline docs, `CLAUDE.md`, `AGENTS.md`, general spec templates, and the `.agents/` multi-agent harness |
+| [`/akili-propose <change-name-or-spec-path>`](akili-propose.md) | Aligning on intent before full specification | `proposal.md` under `docs/specs/<spec-path>/` |
+| [`/akili-specify <spec-path>`](akili-specify.md) | Planning one bounded change before code | `requirements.md`, `design.md`, `tasks.md` |
+| [`/akili-execute <spec-path>`](akili-execute.md) | Implementing approved tasks via the Leader → Implementer → Reviewer harness | Code/docs changes, updated `tasks.md`, `execution.md` with full PASS/FAIL audit trail |
+| [`/akili-test <spec-path>`](akili-test.md) | Proving behavior with test evidence | `test-report.md` |
+| [`/akili-validate <spec-path>`](akili-validate.md) | Auditing conformance before completion | `validation-report.md` |
+| [`/akili-archive <spec-path>`](akili-archive.md) | Closing completed work after validation | Archived spec folder with `archive-summary.md` |
+| [`/akili-seo <site-domain>`](akili-seo.md) | Setting up GSC ownership and SEO audit evidence | `seo-setup-report.md`, `seo-audit-report.md` |
+
+## Normal Sequence
+
+```text
+/akili-constitution
+/akili-propose <change-name-or-spec-path>
+/akili-specify <spec-path>
+/akili-execute <spec-path>
+/akili-test <spec-path>
+/akili-validate <spec-path>
+/akili-archive <spec-path>
+```
+
+You can skip `/akili-propose` for very small, obvious work. You should not skip validation before archiving unless the user explicitly accepts the risk.
+
+## Source Files
+
+| Command | Source |
+|---|---|
+| `/akili-constitution` | `.claude/commands/akili-constitution.md` |
+| `/akili-propose` | `.claude/commands/akili-propose.md` |
+| `/akili-specify` | `.claude/commands/akili-specify.md` |
+| `/akili-execute` | `.claude/commands/akili-execute.md` |
+| `/akili-test` | `.claude/commands/akili-test.md` |
+| `/akili-validate` | `.claude/commands/akili-validate.md` |
+| `/akili-archive` | `.claude/commands/akili-archive.md` |
+| `/akili-seo` | `.claude/commands/akili-seo.md` |

package/docs/commands/akili-archive.md

@@ -0,0 +1,65 @@
+# `/akili-archive`
+
+Move a completed spec into historical archive after implementation, testing, and validation.
+
+## Usage
+
+```text
+/akili-archive <spec-path>
+```
+
+Examples:
+
+```text
+/akili-archive changes/add-remember-me
+/akili-archive bugfix/login-redirect
+/akili-archive enhancements/renewals
+```
+
+## Use When
+
+- The spec is complete.
+- Required tasks are `[x]`, or incomplete work is explicitly accepted as follow-up.
+- Test and validation evidence exist or their absence is explicitly accepted.
+- No unresolved FAIL findings remain.
+
+## Output
+
+Moves:
+
+```text
+docs/specs/<spec-path>/
+```
+
+to:
+
+```text
+docs/specs/archive/YYYY-MM-DD-<safe-name>/
+```
+
+`<safe-name>` replaces `/` with `--`.
+
+## Archive Summary
+
+Before moving, the command creates or updates:
+
+```text
+docs/specs/<spec-path>/archive-summary.md
+```
+
+The summary captures delivered requirements, files changed, test evidence, validation summary, accepted warnings, follow-ups, and historical notes.
+
+## Constitution & Graph Sync
+
+Before moving the folder, the command consumes the `## Constitution Impact` notes recorded in `execution.md` during `/akili-execute`:
+
+- creates or updates child `CLAUDE.md`/`AGENTS.md` guides for new or reshaped modules (thin, module-specific, never duplicating root rules)
+- adds or refreshes the child entries in the parent guides' `## Module Guides` index
+- updates root-guide statements the change made stale
+- recommends a CodeGraph re-index when `.codegraph/` exists
+
+## Guardrails
+
+- Do not delete completed specs.
+- Do not overwrite an existing archive folder.
+- If archive readiness is unclear, ask whether to validate first, proceed with accepted risk, or keep the spec active.

package/docs/commands/akili-constitution.md

@@ -0,0 +1,91 @@
+# `/akili-constitution`
+
+Establish or strengthen the project-wide AKILI foundation and scaffold the multi-agent harness.
+
+## Usage
+
+```text
+/akili-constitution
+```
+
+## Use When
+
+- Starting a new repository.
+- Existing project docs are missing, stale, or inconsistent.
+- A major product pivot changed the project's baseline assumptions.
+- Agents need stable `CLAUDE.md` and `AGENTS.md` guidance.
+- The project does not yet have a `.agents/` directory powering `/akili-execute`.
+
+## Behavior
+
+The command classifies the repository into one of three modes and adjusts its behavior accordingly.
+
+| Mode | Meaning | Constitution Behavior | `.agents/` Behavior |
+|---|---|---|---|
+| Brand-new (Seed Setup) | No code, no AKILI-SPECS docs | Draft baseline from user intent, chosen stack, assumptions, open questions | Copy default Leader / Implementer / Reviewer personas verbatim |
+| Legacy (Discovery Setup) | Real code exists, no AKILI-SPECS baseline | Inspect repository reality (CodeGraph preferred) before drafting; synthesize from evidence | Copy defaults then customize with detected stack, design tokens, lint and test commands |
+| Active AKILI-SPECS (Safe Update) | AKILI-SPECS baseline already present, custom `.agents/` may exist | Upgrade weak sections, fill missing files non-destructively | Never overwrite existing personas — only append minimal upgrade blocks |
+
+For Legacy and Active-AKILI-SPECS modes, if `.codegraph/` exists CodeGraph is used for semantic exploration; if it is missing and the CLI is available, the agent asks before initializing it.
+
+## Outputs
+
+Creates or enhances:
+
+- `docs/prd.md`
+- `docs/ux-ui/design.md`
+- `docs/trd/trd.md`
+- `docs/specs/general-setup/requirements.md`
+- `docs/specs/general-setup/design.md`
+- `docs/specs/general-setup/task.md`
+- `CLAUDE.md`
+- `AGENTS.md`
+- `.agents/leader.md`
+- `.agents/implementer.md`
+- `.agents/reviewer.md`
+
+Projects created before the TRD naming may still have `docs/system-design/design.md` (UX/UI blueprint) and `docs/detailed-design/detailed-design.md` (technical blueprint). The constitution treats those as the existing UX/UI Design document and TRD, and in Active-AKILI-SPECS mode offers to migrate them to `docs/ux-ui/design.md` and `docs/trd/trd.md`.
+
+The root guides also carry a `## Module Guides` index: modules whose conventions diverge from the root get a thin child `CLAUDE.md`/`AGENTS.md`, and every child guide must be referenced from that index. `/akili-execute` records new-module impact notes and `/akili-archive` syncs the guides and recommends a CodeGraph re-index.
+
+## Multi-Agent Harness Scaffolding
+
+`.agents/` is the source of truth for the multi-agent loop that `/akili-execute` runs (Leader → Implementer → Reviewer). The constitution seeds it from the packaged defaults shipped by the installer:
+
+- Claude Code: `~/.claude/akili/templates/{leader,implementer,reviewer}.md`
+- OpenCode: `~/.config/opencode/akili/templates/{leader,implementer,reviewer}.md`
+- Antigravity: `~/.gemini/config/akili/templates/{leader,implementer,reviewer}.md`
+
+If packaged templates are not available, the constitution drafts equivalent personas inline using the structure documented in `/akili-execute` (rework loop, PASS/FAIL output contract, AKILI commit standard, Pivot Protocol).
+
+The `.agents/` directory is tool-agnostic: pure Markdown + YAML frontmatter, resolved relative to the active workspace, and used by Claude Code, OpenCode, and Google Antigravity (`invoke_subagent`).
+
+## Model Routing Scaffolding
+
+Step 7C adds or upgrades a `## Model Routing` section in the project's root `AGENTS.md` and `CLAUDE.md`: a capability-tier registry that maps each AKILI-SPECS phase to a model **per tool** (Claude Code and OpenCode). It is guidance only — no `model:` frontmatter is added and the installer is unchanged. The registry enforces **author ≠ auditor** (the Reviewer runs on a different model than the Implementer) and, in Active-AKILI-SPECS mode, is non-destructive: an existing customized registry is preserved and only gaps are filled. See [Model Routing](../model-routing.md) for the tiers and the default registry.
+
+- `product-manager-toolkit`
+- `ui-ux-pro-max`
+- `frontend-design`
+- `stitch-design`
+- `nestjs-expert`
+- `api-design-principles`
+- `error-handling-patterns`
+- `aws-serverless`
+- `shadcn-ui`
+- `tailwind-design-system`
+- `vercel-react-best-practices`
+
+## Next Step
+
+After approving the baseline and confirming `.agents/` is in place, start a change:
+
+```text
+/akili-propose <change-name-or-spec-path>
+```
+
+For a small, obvious change, you may start with:
+
+```text
+/akili-specify <spec-path>
+```

package/docs/commands/akili-execute.md

@@ -0,0 +1,93 @@
+# `/akili-execute`
+
+Implement the next eligible task from an approved spec path using the AKILI **Leader → Implementer → Reviewer** multi-agent harness.
+
+## Usage
+
+```text
+/akili-execute <spec-path>
+```
+
+## Use When
+
+- `requirements.md`, `design.md`, and `tasks.md` are approved.
+- `.agents/` is in place (scaffolded by `/akili-constitution`).
+- You want incremental, audited execution instead of broad untracked implementation.
+- A previous task is marked `[~]` and should be resumed.
+
+## Inputs
+
+Reads:
+
+- `docs/specs/<spec-path>/requirements.md`
+- `docs/specs/<spec-path>/design.md`
+- `docs/specs/<spec-path>/tasks.md`
+- `docs/specs/<spec-path>/execution.md` when present
+- Constitution docs (`docs/prd.md`, `docs/ux-ui/design.md`, `docs/trd/trd.md`)
+- `CLAUDE.md` and `AGENTS.md`
+- `.agents/leader.md`, `.agents/implementer.md`, `.agents/reviewer.md`
+
+## Behavior
+
+`/akili-execute` runs each task through a bounded rework loop. The caller acts as the **Leader** and delegates to two subordinate roles:
+
+| Role | File | Responsibilities |
+|---|---|---|
+| Leader | `.agents/leader.md` | Picks the next task, delegates, enforces the loop, updates `tasks.md` and `execution.md`, commits |
+| Implementer | `.agents/implementer.md` | Writes code strictly within task scope, applies design tokens, runs verification before reporting |
+| Reviewer | `.agents/reviewer.md` | Read-only diff audit; emits `STATUS: PASS` or `STATUS: FAIL` with structured findings |
+
+### Per-task loop
+
+```text
+1. Leader selects the next [ ] or [~] task whose dependencies are complete
+2. Spawn Implementer with task scope, design context, and prior FAIL feedback (if rework)
+3. Implementer writes code and runs the verification command
+4. Leader extracts git diff
+5. Spawn Reviewer with diff + relevant spec slices
+6. Reviewer returns STATUS: PASS or STATUS: FAIL
+
+if PASS  → update tasks.md to [x], append execution.md, commit, advance to next task
+if FAIL  → log issues; if attempts < 3, respawn Implementer with the unchanged Reviewer report
+if 3 consecutive FAILs → HALT, mark task [~], present full audit trail
+```
+
+On PASS, if the task created a new module/package or moved a module boundary, the Leader also appends a `## Constitution Impact: <Task ID>` block to `execution.md` (child guide needed, parent `## Module Guides` index entry, pending CodeGraph re-index). `/akili-archive` consumes these notes during Constitution & Graph Sync.
+
+### Reviewer output contract
+
+On `FAIL`, every finding lists three fields so the Implementer has actionable instructions on the next loop iteration:
+
+- **Discovered Issue** — what is incorrect or missing.
+- **Violated Rule** — the specific spec document and section that the diff contradicts.
+- **Remediation Suggestion** — what the next Implementer attempt must change.
+
+## Outputs
+
+- Focused code or documentation changes (only after Reviewer PASS).
+- Updated `tasks.md` with `[x]`, `[~]`, or `[ ]` status.
+- Updated `execution.md` with files changed, requirements covered, decisions, every Implementer attempt, every Reviewer verdict, verification evidence, and final status (PASS / HALT / pivot).
+- Commit prefixed with `[SPEC:<spec-path>]`.
+
+## Guardrails
+
+- **Maximum retries.** Hard ceiling of 3 rework attempts per task. After 3 consecutive FAILs the loop HALTS and presents the audit trail.
+- **Structured feedback.** The Reviewer's FAIL report is passed back unchanged to the next Implementer — no paraphrasing.
+- **No scope creep.** The Implementer keeps changes minimal and within task scope; broad refactors require user approval.
+- **No completion without PASS.** A task is never marked `[x]` until the Reviewer PASSes.
+- **Pivot Protocol takes precedence.** If discovery proves the spec itself is wrong, the loop stops immediately and a `## Pivot Record` is opened in `execution.md` for user sign-off — rework retries are not consumed on a broken spec.
+
+## Cross-tool support
+
+The `.agents/` directory is pure Markdown + YAML frontmatter and is resolved relative to the active workspace.
+
+- **Claude Code / OpenCode:** Leader delegates by spawning focused subagent or sub-prompt contexts seeded with the persona file plus task/diff context.
+- **Google Antigravity:** Leader calls `invoke_subagent` using prompts read from `.agents/`.
+
+## Next Step
+
+Continue executing tasks until implementation is complete, then run:
+
+```text
+/akili-test <spec-path>
+```

package/docs/commands/akili-propose.md

@@ -0,0 +1,65 @@
+# `/akili-propose`
+
+Create a lightweight, reviewable proposal before full specification.
+
+## Usage
+
+```text
+/akili-propose <change-name-or-spec-path>
+```
+
+Examples:
+
+```text
+/akili-propose add-remember-me
+/akili-propose bugfix/login-redirect
+/akili-propose enhancements/renewals
+```
+
+## Path Rules
+
+| Input | Spec Path | Proposal Path |
+|---|---|---|
+| `add-remember-me` | `changes/add-remember-me` | `docs/specs/changes/add-remember-me/proposal.md` |
+| `bugfix/login-redirect` | `bugfix/login-redirect` | `docs/specs/bugfix/login-redirect/proposal.md` |
+
+Bare names default to `changes/<name>`. Paths containing `/` are used as provided under `docs/specs/`.
+
+## Use When
+
+- The change needs stakeholder review before detailed specs.
+- Scope, non-goals, risks, or affected systems are uncertain.
+- Multiple implementation approaches are possible.
+- Existing behavior may need added, modified, or removed requirements.
+
+## Output
+
+Creates or updates:
+
+```text
+docs/specs/<spec-path>/proposal.md
+```
+
+## Proposal Sections
+
+- Document Control
+- Intent
+- Problem / Current Behavior
+- Proposed Outcome
+- Scope
+- Non-Goals
+- Affected Users, Systems, And Specs
+- Requirement Delta Preview
+- Approach Options
+- Recommended Approach
+- Risks, Dependencies, And Open Questions
+- Success Criteria
+- Next Step
+
+## Next Step
+
+After approval:
+
+```text
+/akili-specify <spec-path>
+```

package/docs/commands/akili-seo.md

@@ -0,0 +1,75 @@
+# `/akili-seo`
+
+Provision Google Search Console ownership for a domain, run a technical SEO audit, and write reports under a spec path.
+
+## Usage
+
+```text
+/akili-seo <site-domain>
+```
+
+Examples:
+
+```text
+/akili-seo example.com
+/akili-seo seo/example.com
+```
+
+## Path Rules
+
+Bare domains default to:
+
+```text
+docs/specs/seo/<domain>/
+```
+
+Paths containing `/` are treated as explicit spec paths under `docs/specs/`.
+
+## Prerequisites
+
+- Google Cloud service account JSON key stored outside the repo.
+- Site Verification API enabled.
+- Search Console API enabled.
+- DNS provider access for the target domain.
+- `gsc` MCP configured from `.mcp.json.example`.
+- Python dependencies for the bundled verification helper: `google-auth` and `google-api-python-client`.
+
+The Web Search Indexing API is not required for generic sites. Google only honors it for `JobPosting` and `BroadcastEvent` schemas.
+
+## Outputs
+
+Creates or updates:
+
+```text
+docs/specs/<spec-path>/seo-setup-report.md
+docs/specs/<spec-path>/seo-audit-report.md
+```
+
+## Audit Areas
+
+- DNS TXT verification and property ownership
+- Search Console property visibility
+- sitemap submission and sitemap URL inventory
+- URL inspection and index coverage
+- structured data warnings and errors
+- search analytics by query, page, country, and device
+- server-rendered content checks with Googlebot user agent
+- internal linking quick check
+- on-page audit (titles, metas, headings, canonicals, hreflang) via the `seo-audit` skill
+- prioritized remediation plan
+- implementation prompt for high-severity fixes
+
+## Skills
+
+The audit phase loads the packaged [`seo-audit`](../skills/seo-audit.md) skill: findings follow its Issue / Impact / Evidence / Fix / Priority format and are weighted by its priority order (crawlability → technical → on-page → content → authority). `systematic-debugging` applies when index data is inconsistent with site reality.
+
+## Helper Resources
+
+| Resource | Purpose |
+|---|---|
+| `scripts/gsc_verify.py` | Calls Site Verification API for token and verify operations |
+| `.mcp.json.example` | Reference MCP config for `@mikusnuz/gsc-mcp` |
+
+## When To Run
+
+Run after deployment, after major content changes, after schema changes, or when Search Console ownership needs to be provisioned for a service account.

package/docs/commands/akili-specify.md

@@ -0,0 +1,69 @@
+# `/akili-specify`
+
+Generate the requirements, design, and task plan for one bounded feature, bugfix, enhancement, or module.
+
+## Usage
+
+```text
+/akili-specify <spec-path>
+```
+
+Examples:
+
+```text
+/akili-specify loan
+/akili-specify enhancements/renewals
+/akili-specify admin/user-management
+```
+
+## Use When
+
+- A proposal has been approved and needs full specification.
+- A small change is clear enough to specify directly.
+- A feature needs behavior, design, task, and verification traceability before coding.
+
+## Inputs
+
+Reads context from:
+
+- `docs/specs/<spec-path>/proposal.md` when present
+- `docs/specs/general-setup/`
+- `docs/prd.md`
+- `docs/ux-ui/design.md`
+- `docs/trd/trd.md`
+- related specs under `docs/specs/`
+- root and package-level agent guidance files
+
+## Outputs
+
+Creates or updates:
+
+```text
+docs/specs/<spec-path>/requirements.md
+docs/specs/<spec-path>/design.md
+docs/specs/<spec-path>/tasks.md
+```
+
+## Documentation Depth
+
+| Depth | Use For |
+|---|---|
+| Lite | Small bugfixes, copy updates, narrow UI tweaks |
+| Standard | Normal features and enhancements |
+| Full | Risky, cross-cutting, API, data, auth, migration, or high-impact work |
+
+## Key Rules
+
+- Requirements describe observable behavior, not implementation details.
+- Key requirements include Given/When/Then scenarios.
+- Design extends the current architecture instead of replacing it.
+- Tasks reference requirements, design sections, dependencies, done criteria, verification, and relevant skills.
+- The user approves requirements, design, and tasks before implementation begins.
+
+## Next Step
+
+After approval:
+
+```text
+/akili-execute <spec-path>
+```