Skip to content

CLAUDE.md

Latest commit

 

History

History
307 lines (223 loc) · 17.3 KB

CLAUDE.md

File metadata and controls

307 lines (223 loc) · 17.3 KB

ask-legion

System prompt for Claude Code. Do not remove or override. ASK (Agentic SDLC Kit) — the perfect fusion of SDD (spec-driven discipline) and TDD (test-driven discipline) for teams building software with AI agents.

Self-contained at the workflow layer. No plugin marketplace to install from, no remote skill source to sync — every legion agent, skill, hook, and script ships in this repo (.claude/, scripts/, hooks/). Updates are git pulls, not network calls. Host prerequisites (must already be on the developer machine before bash scripts/setup.sh): bash, git, node ≥ 18, npm, jq. The only runtime dependency the workflow itself adds is GitNexus (code-graph MCP), installed via npm install -g gitnexus during setup. "Self-contained" therefore means "no plugin marketplace, no skill sync, no SaaS issue tracker", not "zero external binaries on the host".

Brand: ask-legion Roles: 3 legion agents (legion-spec-owner, legion-principal, legion-engineer) Skills: 10 legion discipline skills (legion:brainstorming … legion:verification-before-completion) Safety: legion-scan hooks (secrets-scan, protected-files, legion-guard) + GitNexus impact gates Slash commands: /legion:spec, /legion:design, /legion:implement, /legion:ship, /legion:status, /legion:roles

Core philosophy: SDD ⨯ TDD

┌────────────────── ask-legion ────────────────────┐
│                                                  │
│   SDD  (legion agents)        TDD  (legion       │
│   3 roles, file-based         skills + commit    │
│   state machine, phase        ordering, machine- │
│   gates                       enforced)          │
│                                                  │
│   ──────────── one product ────────────          │
│                                                  │
├──── safety net (always-on, hook-level) ──────────┤
│   legion-scan + legion-guard + GitNexus          │
└──────────────────────────────────────────────────┘
  • SDD layer (legion agents) decides WHAT to build and WHO owns each step. The 3 agents — legion-spec-owner, legion-principal, legion-engineer — are self-contained personas in .claude/agents/legion-*.md. The story state machine (scripts/story.sh) is the connective tissue.
  • TDD layer (legion skills) decides HOW work is done. Each agent invokes specific skills from .claude/skills/legion/. Discipline is enforced by code: TDD task ordering at story promotion, TDD commit ordering at pre-merge, verification-before-completion at the gate.
  • Safety net runs at the hook level and cannot be skipped. secrets-scan blocks hardcoded tokens; protected-files blocks edits to .env/.pem/credentials.json; legion-guard blocks Agent dispatch to a missing role file; GitNexus enforces impact-aware editing.

5-Step Workflow

The pipeline collapses into 5 logical steps, owned by 3 roles:

Step 1 — Spec (legion-spec-owner)

Phases internal to SO: brief → PRD → UX (if UI). Single role drives the entire WHAT/WHY chain.

  • docs/brief.md (skill: legion:brainstorming)
  • docs/prd.md (skill: legion:brainstorming)
  • docs/front-end-spec.md (if UI — skill: legion:brainstorming)

Step 2 — Design (legion-principal)

Principal owns architecture decisions and the binding tech stack.

  • docs/architecture.md (skills: legion:brainstorming, legion:writing-plans; GitNexus: query, context)

Step 3 — Validate + shard + story (legion-spec-owner)

After architecture lands, SO runs validation (8 checks), shards oversized docs, produces epics, and authors stories with embedded GitNexus context.

  • docs/epics/{epic}.md
  • docs/stories/{epic}.{story}.md (skills: legion:using-git-worktrees, legion:dispatching-parallel-agents)
  • GitNexus: context (embedded into story body)
  • TDD ordering layer 1: every task tagged [T]/[I]/[V]; every [I] preceded by a [T] (gated by scripts/check-tdd-ordering.sh on Ready)

Step 4 — Implement (legion-engineer)

Engineer picks up status: Ready stories.

  • Skills: legion:test-driven-development, legion:systematic-debugging, legion:verification-before-completion, legion:executing-plans (if complex)
  • GitNexus: impact (mandatory pre-edit), rename (for refactors), detect_changes (self-check)
  • legion-scan hooks: always on
  • TDD ordering layer 2: first feat:/fix: commit must follow at least one test: commit on the branch (gated by scripts/check-commit-tdd.sh in make pre-merge-check)

Step 5 — Gate + ship (legion-principal)

Principal runs Gates 0–4 on stories in Review.

  • Skills: legion:verification-before-completion
  • GitNexus: detect_changes (mandatory pre-ship)
  • Gate 0: make tdd-check (re-runs both TDD ordering layers)
  • legion-scan: make scan

Engineer uses legion:receiving-code-review when Principal returns the story with findings.

Role ↔ Agent File ↔ Skill Mapping

Role Agent file Required Legion skills GitNexus tools
Spec Owner legion-spec-owner.md brainstorming, using-git-worktrees, dispatching-parallel-agents context (embedded into stories)
Principal IE legion-principal.md brainstorming, writing-plans, verification-before-completion query, context, detect_changes
Engineer legion-engineer.md test-driven-development, systematic-debugging, verification-before-completion (+ executing-plans, receiving-code-review when applicable) impact, rename, detect_changes

Enforced by scripts/lint-agents.sh — every required skill MUST appear literally in the agent file.

Hard Rules (non-negotiable)

  1. Every code change goes through a Story. Hotfix = micro-story. No direct edits.
  2. Engineer MUST run gitnexus_impact before editing any symbol. HIGH/CRITICAL → escalate to legion-principal.
  3. TDD ordering is enforced at two layers (machine-checked, no honor system):
    • Layer 1 — Story spec: every task in ## Tasks carries a marker [T] (test) / [I] (impl) / [V] (verify-only). Every [I] MUST have at least one [T] earlier in the list. scripts/check-tdd-ordering.sh runs in scripts/story.sh on Ready and Review transitions — violations block the transition.
    • Layer 2 — Branch commits: the first feat: or fix: commit on a branch MUST be preceded by at least one test: commit. Pure-refactor branches (only refactor:) are intentionally exempt — refactors must not change observable behavior, so the existing test suite is what proves the refactor is safe. Forcing a brand-new test: per refactor would either produce duplicate-of-existing tests (noise) or invite gaming the gate. The implicit safeguard: pre-existing tests must still pass after the refactor (make pre-merge-check runs them at Gate 0). If a refactor changes a contract or adds a code path, it is misclassified — relabel as feat:/fix: and add the missing test: commit. scripts/check-commit-tdd.sh runs in make pre-merge-check — violations block the gate.
    • Engineer MUST also confirm each test fails for the right reason BEFORE writing the code that makes it pass.
  4. Engineer MUST paste actual command output when claiming a task done. No "should work" claims.
  5. Principal MUST run gitnexus_detect_changes before marking Done. Scope creep → return story to Engineer.
  6. 1 Story = 1 branch = 1 worktree = 1 PR. Never bundle stories.
  7. legion-scan hook blocks cannot be bypassed with --no-verify. Fix the root cause.
  8. Engineer NEVER marks a story Done. Only Principal can. The split between Engineer (does work + self-verifies) and Principal (gates work) is what preserves the "second pair of eyes" guarantee — every story crosses an agent boundary before merge.

Fast-path (still goes through legion)

Fast-path skips Steps 1+2+3-validate. Spec Owner story authoring + Engineer + Principal gating are NEVER skipped. Use only if ALL of these are true:

  • ≤ 2 files changed (check with git diff --stat against main on a dry branch)
  • No schema change (no CREATE TABLE, ALTER TABLE, migration files)
  • No new user-visible behavior (no UX decisions, no new endpoints, no new permissions)
  • No dependency added (no new entries in package.json / go.mod / pyproject.toml / Cargo.toml)

If any is false → run the full 5 steps.

Scenario Roles to run
Hotfix / typo / doc fix SO micro-story → Engineer → Principal
Bug fix (test added) SO story → Engineer (TDD) → Principal
Feature ≤ 1 day AND all fast-path criteria pass SO mini-PRD + story + Engineer + Principal
Feature > 1 day, or fast-path criterion fails Full 5 steps
Greenfield / new module / new service Full 5 steps

When in doubt: run the full flow. Skipping is the expensive mistake.

Anti-Patterns

Do Not Instead
Write code before a Story exists Spec Owner creates Story first
Skip Principal for brownfield Principal surveys with GitNexus before design
Trust Engineer's "should work" Principal demands pasted evidence
Find-and-replace a rename gitnexus_rename with dry_run=true
Merge with scope creep Principal returns story; Engineer fixes
Bundle multiple stories in one PR One story per PR, always
Author story tasks without [T]/[I]/[V] markers SO writes markers; check-tdd-ordering.sh blocks Ready if missing
feat: commit before any test: on the branch Stage TDD: test: commit first, then feat:; check-commit-tdd.sh blocks merge
Bug fix without a reproducing failing-test commit Add a test: commit that reproduces the bug, then fix: — every fix: requires a test: predecessor
Engineer self-promoting story to Done Only Principal can mark Done — scripts/story.sh done is a Principal-only command in practice

Commit Discipline

  • 1 commit per task in the story (one [T] task → one test: commit; one [I] task → one feat:/fix:/refactor: commit).
  • Message format: <type>: <description> (feat, fix, refactor, test, docs, chore). Conventional-commits scope (scope) and breaking-change ! are allowed.
  • TDD ordering (see Hard Rule #3): on a story branch, the first feat:/fix: MUST be preceded by at least one test: commit.
  • Tests must pass after every commit. Failing 3× on one task → stop, re-check story, escalate to legion-spec-owner.

Security

  • legion-scan PreToolUse hooks (secrets-scan.sh, protected-files.sh) block secrets and protected files automatically — vendored, no external runtime dependency.
  • Run make scan for whole-repo audit (vendored — no npx call).
  • session-end hook scans staged files for secrets + debug artifacts on Stop.
  • Never hardcode credentials. If a hook blocks unexpectedly, fix the underlying issue rather than bypassing.

Setup

git init  # if not already a repo
bash scripts/setup.sh

Installs:

  • legion agents → .claude/agents/legion-*.md (vendored — 3 files)
  • legion skills → .claude/skills/legion/*/SKILL.md (vendored — 10 files)
  • legion-scan hooks → merged into ~/.claude/settings.json (vendored)
  • GitNexus → npm install -g gitnexus (only external dependency)

After setup, restart Claude Code. No plugins to install. No marketplace dependencies.

The block below is auto-managed by npx gitnexus analyze between the gitnexus:start / gitnexus:end markers. Do not edit by hand — your changes will be overwritten on the next index. To customize the legion-specific short-form rules, edit .claude/skills/legion-core/gitnexus-reference.md instead (loaded on demand by agents).

GitNexus — Code Intelligence

This project is indexed by GitNexus as ask-legion (45 symbols, 34 relationships, 0 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.

If any GitNexus tool warns the index is stale, run npx gitnexus analyze in terminal first.

Always Do

  • MUST run impact analysis before editing any symbol. Before modifying a function, class, or method, run gitnexus_impact({target: "symbolName", direction: "upstream"}) and report the blast radius (direct callers, affected processes, risk level) to the user.
  • MUST run gitnexus_detect_changes() before committing to verify your changes only affect expected symbols and execution flows.
  • MUST warn the user if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
  • When exploring unfamiliar code, use gitnexus_query({query: "concept"}) to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
  • When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use gitnexus_context({name: "symbolName"}).

When Debugging

  1. gitnexus_query({query: "<error or symptom>"}) — find execution flows related to the issue
  2. gitnexus_context({name: "<suspect function>"}) — see all callers, callees, and process participation
  3. READ gitnexus://repo/ask-legion/process/{processName} — trace the full execution flow step by step
  4. For regressions: gitnexus_detect_changes({scope: "compare", base_ref: "main"}) — see what your branch changed

When Refactoring

  • Renaming: MUST use gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true}) first. Review the preview — graph edits are safe, text_search edits need manual review. Then run with dry_run: false.
  • Extracting/Splitting: MUST run gitnexus_context({name: "target"}) to see all incoming/outgoing refs, then gitnexus_impact({target: "target", direction: "upstream"}) to find all external callers before moving code.
  • After any refactor: run gitnexus_detect_changes({scope: "all"}) to verify only expected files changed.

Never Do

  • NEVER edit a function, class, or method without first running gitnexus_impact on it.
  • NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
  • NEVER rename symbols with find-and-replace — use gitnexus_rename which understands the call graph.
  • NEVER commit changes without running gitnexus_detect_changes() to check affected scope.

Tools Quick Reference

Tool When to use Command
query Find code by concept gitnexus_query({query: "auth validation"})
context 360-degree view of one symbol gitnexus_context({name: "validateUser"})
impact Blast radius before editing gitnexus_impact({target: "X", direction: "upstream"})
detect_changes Pre-commit scope check gitnexus_detect_changes({scope: "staged"})
rename Safe multi-file rename gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})
cypher Custom graph queries gitnexus_cypher({query: "MATCH ..."})

Impact Risk Levels

Depth Meaning Action
d=1 WILL BREAK — direct callers/importers MUST update these
d=2 LIKELY AFFECTED — indirect deps Should test
d=3 MAY NEED TESTING — transitive Test if critical path

Resources

Resource Use for
gitnexus://repo/ask-legion/context Codebase overview, check index freshness
gitnexus://repo/ask-legion/clusters All functional areas
gitnexus://repo/ask-legion/processes All execution flows
gitnexus://repo/ask-legion/process/{name} Step-by-step execution trace

Self-Check Before Finishing

Before completing any code modification task, verify:

  1. gitnexus_impact was run for all modified symbols
  2. No HIGH/CRITICAL risk warnings were ignored
  3. gitnexus_detect_changes() confirms changes match expected scope
  4. All d=1 (WILL BREAK) dependents were updated

Keeping the Index Fresh

After committing code changes, the GitNexus index becomes stale. Re-run analyze to update it:

npx gitnexus analyze

If the index previously included embeddings, preserve them by adding --embeddings:

npx gitnexus analyze --embeddings

To check whether embeddings exist, inspect .gitnexus/meta.json — the stats.embeddings field shows the count (0 means no embeddings). Running analyze without --embeddings will delete any previously generated embeddings.

Claude Code users: A PostToolUse hook handles this automatically after git commit and git merge.

CLI

Task Read this skill file
Understand architecture / "How does X work?" .claude/skills/gitnexus/gitnexus-exploring/SKILL.md
Blast radius / "What breaks if I change X?" .claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md
Trace bugs / "Why is X failing?" .claude/skills/gitnexus/gitnexus-debugging/SKILL.md
Rename / extract / split / refactor .claude/skills/gitnexus/gitnexus-refactoring/SKILL.md
Tools, resources, schema reference .claude/skills/gitnexus/gitnexus-guide/SKILL.md
Index, status, clean, wiki CLI commands .claude/skills/gitnexus/gitnexus-cli/SKILL.md