Skip to content

How-to-guides

Task-oriented walkthroughs. Each guide answers a single concrete question.

Plan-suite pipeline

How do I refine raw content into a spec?

Invoke /plan-spec with the raw content as input. The Forge role runs six transformation phases (Discovery, Meticulous Consideration, Potency Mapping, Preservation Verification, Expertise Application, Question-Resolution Sweep) and emits the consolidated spec at plans/{suite}/_spec/spec.md. See src/apothem/commands/plan-spec.md for the full protocol.

How do I generate a plan suite from a spec?

Invoke /plan-generate <suite-name> once the spec lives at plans/{suite}/_spec/spec.md. The generator emits the canonical infrastructure files plus the per-phase phases/NN-kebab-topic/PHASE.md files. See src/apothem/commands/plan-generate.md.

How do I review a generated plan?

Invoke /plan-review path/to/plan-suite/. The reviewer applies the eight planning techniques and emits scorecards. Failing scorecards block execution at SHARED+ until resolved. See src/apothem/commands/plan-review.md.

How do I execute a plan?

Invoke /plan-execute path/to/plan-suite/ [phase-id]. Without a phase-id, the next pending phase runs. With a specific id, only that phase runs. See src/apothem/commands/plan-execute.md.

How do I check plan status?

Invoke /plan-status path/to/plan-suite/ [--verbose]. Read-only report. See src/apothem/commands/plan-status.md.

Authoring artifacts

How do I add a new rule?

  1. Pick a kebab-case file name under src/apothem/rules/, e.g. src/apothem/rules/my-new-rule.md.
  2. Author the frontmatter (name, description, type: instruction, optional pathFilter).
  3. Write the body with the canonical sections: Purpose, Obligations, Seriousness Scaling, Anti-Patterns, Enforcement, Bindings.
  4. Add a row to CLAUDE.md §7.2 Rules registry.
  5. Run python scripts/dev/validate_ecosystem.py --check frontmatter-cohort to verify.

How do I add a new agent?

  1. Pick a kebab-case file name under src/apothem/agents/, e.g. src/apothem/agents/my-agent.md.
  2. Author the frontmatter (name, description, type: agent, allowedTools, maxTurns, version).
  3. Write the system prompt as the body.
  4. Add a row to CLAUDE.md §7.3 Agents registry.

How do I add a new hook?

  1. Author a context message under src/apothem/hooks/messages/<event>-<scope>.md.
  2. Wire the hook in both settings.json and settings-unix.json atomically.
  3. Update CLAUDE.md §7.4 Hooks Pipeline table.
  4. Run python scripts/dev/validate_ecosystem.py --check hook-validator.

Quality gates

How do I run the local quality gates?

python -m ruff check .
python -m ruff format --check .
python -m mypy
python -m pytest -q
python scripts/dev/validate_ecosystem.py
python scripts/dev/chaos_pass.py

The CI pipeline runs the same set in parallel.

How do I check a single artifact-class frontmatter?

python scripts/dev/validate_ecosystem.py --check frontmatter-cohort