ASK — Agentic SDLC Kit. A workflow toolkit for teams running the full software development lifecycle with AI agents: spec → design → story → implementation → gated merge, with discipline enforced by code rather than convention.
ask-legionis the first reference distribution of ASK — the perfect fusion of SDD (spec-driven discipline) and TDD (test-driven discipline), packaged as a single self-contained.claude/tree. No plugin marketplace, no remote skill sync. Host prerequisites:bash,git,node ≥ 18,npm,jq. The only runtime dependency setup adds is GitNexus (code-graph MCP).
ask-legion bundles 3 spec-driven role agents (Spec Owner, Principal Intelligence Engineer, Intelligence Engineer) and 10 vendored TDD discipline skills (legion:test-driven-development, legion:brainstorming, …) into a single .claude/ tree, plus three always-on safety hooks. The discipline that prevents AI agents from drifting (in scope or in implementation quality) is machine-enforced at two layers, not honor-system.
ask-legion stands on the shoulders of three MIT-licensed projects:
- BMAD-METHOD by Brian Madison — the role-agent persona structure (Identity / Communication Style / Principles / Critical Actions / Hand-off Rules) that shapes
.claude/agents/legion-*.md. - Superpowers by Jesse Vincent — the discipline-skill model behind the 10 vendored
legion:*skills (TDD, brainstorming, writing-plans, executing-plans, …). - ECC AgentShield by Affaan M — the 18 secret-detection patterns wired into
secrets-scanandmake scan.
Full credits and license texts: ATTRIBUTION.md.
| What you have | What you risk |
|---|---|
| SDD only (clear spec, no test enforcement) | Agent writes code that satisfies the spec on the surface but hallucinates edge-case behavior. Spec is right, code is subtly wrong. |
| TDD only (tests-first, no spec) | Agent writes well-tested code for the wrong feature. Tests pass. User gets exactly what they didn't ask for, fast. |
| Both — legion | Spec defines what to build (Spec Owner via brief.md/prd.md). Architecture defines how it fits (Principal via architecture.md). Story decomposes work task-by-task with [T]/[I]/[V] markers (Spec Owner). TDD ordering enforces tests-precede-code at every step (machine-checked, layer 1 + 2). Engineer cannot drift in scope or discipline; Principal gates every story before merge. |
Read the full philosophy: docs/ARCHITECTURE.md
┌────────────────────── ask-legion ───────────────────────┐
│ │
│ SDD layer (legion agents) TDD layer (legion skills)│
│ 3 roles, file artifacts 10 vendored disciplines │
│ File-based state machine Machine-enforced gates │
│ │
│ ─────────────── one product ──────────────── │
│ │
├──── safety net (always-on, hook-enforced) ───────────────┤
│ legion-guard + secrets-scan + protected-files + │
│ GitNexus impact gates │
└──────────────────────────────────────────────────────────┘
5-step pipeline owned by 3 roles:
flowchart LR
S1[legion-spec-owner<br/>brief.md → prd.md →<br/>fe-spec.md if UI] --> D[legion-principal<br/>architecture.md]
D --> S2[legion-spec-owner<br/>validate + shard +<br/>epic.md + story.md<br/>TDD ordering layer 1]
S2 --> E[legion-engineer<br/>code + TDD<br/>layer 2 enforced]
E --> P[legion-principal<br/>Gates 0–4]
P -- Returned --> E
P -- Done --> M[Merge]
classDef so fill:#e6f0ff,stroke:#4a7eff
classDef pie fill:#ffe6f0,stroke:#e74c8c
classDef ie fill:#fff0e6,stroke:#e67e22
class S1,S2 so
class D,P pie
class E ie
1 Story = 1 branch = 1 worktree = 1 PR. No bundling.
Slash commands: /legion:spec /legion:design /legion:implement /legion:ship /legion:status /legion:roles
Requires Node.js ≥ 18, Git, jq.
# In your existing repo:
git clone https://github.com/ongtungduong/ask-legion ../ask-legion
make -C ../ask-legion setup TARGET=$(pwd)
# Or use ask-legion as your starter template:
git clone https://github.com/ongtungduong/ask-legion my-project
cd my-project && make setupSetup installs:
| Component | Where |
|---|---|
| 3 self-contained legion agents | .claude/agents/legion-*.md (vendored) |
| 10 legion discipline skills | .claude/skills/legion/ (vendored) |
| Safety hooks | merged into ~/.claude/settings.json (vendored) |
| GitNexus | npm install -g gitnexus (only external dep) |
| Templates | templates/legion/ for new docs/ skeletons |
| Pre-push githook | core.hooksPath = githooks/ |
Restart Claude Code. Then verify:
make statusExpected:
==> GitNexus (only external dependency)
Status: ✅ up to date
==> Legion agents (vendored)
3/3 legion-*.md present
==> Legion skills (vendored)
10 skill files in .claude/skills/legion/
==> Hooks (vendored)
3 pre-tool hooks active
See GETTING_STARTED.md for a 30-minute walkthrough that takes a feature from /legion:spec to merged story.
| Command | What it does |
|---|---|
make status |
Show inventory of installed legion components |
make tdd-check |
Run both TDD ordering layers (story tasks + branch commits) |
make scan |
Whole-repo audit for secrets + protected files |
make pre-merge-check |
Gate 0 (TDD) + Gate 1 (security) + reindex — run before Principal review |
make story ARGS="ready 1.3" |
Transition story status (wraps scripts/story.sh) |
make story-list |
List all stories with status |
make test-scripts |
Regression tests for helper scripts (100 cases across TDD ordering, hooks, fast-path, lint-agents) |
make lint-agents |
Validate .claude/agents/legion-*.md integrity |
make index |
Re-index codebase with GitNexus (auto-runs after commits via hook) |
Full reference: docs/OPERATIONS.md
| Role | Combines | Owns |
|---|---|---|
| Spec Owner | BA + PM + UX + PO + SM | The full WHAT/WHY chain: brief → PRD → UX → epics → stories. Story authoring with [T]/[I]/[V] markers. |
| Principal IE | System Architect + QA gate authority | Architecture (docs/architecture.md) + Gates 0–4 + Done/Returned authority + escalation hub for HIGH/CRITICAL impact |
| Engineer | Dev + self-verification | Code commits, TDD per task, gitnexus_impact pre-edit, make pre-merge-check self-check, requests Review |
Discipline preserved without a separate human QA: the Principal gate is machine-enforced (Gates 0–4 are bash + GitNexus + scan), and the Engineer/Principal split prevents self-promotion to Done.
| You want to | Read |
|---|---|
| Walk through your first feature | GETTING_STARTED.md |
| Run ask-legion as a team (1–8+ size profiles, greenfield + brownfield setup, role rotation, coverage) | docs/TEAM_HANDBOOK.md |
| Understand the SDD ⨯ TDD design | docs/ARCHITECTURE.md |
| See how each role works in detail | docs/WORKFLOW.md |
| Master the TDD ordering gates | docs/TDD_ENFORCEMENT.md |
| Understand hooks + threat model | docs/SAFETY.md |
| Run daily ops + troubleshoot | docs/OPERATIONS.md |
| Read the canonical system prompt | CLAUDE.md |
| Cross-platform (Copilot, Antigravity) | AGENTS.md |
| See worked examples | docs/examples/ |
| See a reference story | docs/stories/EXAMPLE.1.1.md |
.
├── .claude/
│ ├── agents/ # 3 self-contained legion agents
│ │ └── legion-{spec-owner,principal,engineer}.md
│ ├── skills/
│ │ ├── legion/ # 10 vendored discipline skills
│ │ ├── legion-core/ # gitnexus reference (long-form)
│ │ └── gitnexus/ # gitnexus operational skills
│ ├── commands/legion/ # slash commands /legion:*
│ └── settings.json # hooks + permissions
├── scripts/
│ ├── setup.sh # one-shot installer
│ ├── story.sh # story state machine
│ ├── scan.sh # whole-repo audit (vendored)
│ ├── check-tdd-ordering.sh # TDD layer 1 gate
│ ├── check-commit-tdd.sh # TDD layer 2 gate
│ ├── lint-agents.sh # legion agent integrity
│ ├── test-{tdd-ordering,commit-tdd}.sh # regression tests
│ ├── session-end-check.sh # Stop-time scan
│ └── hooks/
│ ├── legion-guard.sh # Agent dispatch gate
│ ├── secrets-scan.sh # PreToolUse secret blocker
│ ├── protected-files.sh # PreToolUse file blocker
│ └── gitnexus-reindex.sh # PostToolUse reindex
├── docs/
│ ├── ARCHITECTURE.md # SDD ⨯ TDD philosophy + ADRs
│ ├── WORKFLOW.md # 5-step pipeline detailed
│ ├── TDD_ENFORCEMENT.md # 2-layer TDD gates
│ ├── SAFETY.md # hooks + scan + threat model
│ ├── OPERATIONS.md # Make + story.sh + FAQ
│ ├── examples/ # filled artifacts (brief, prd, arch, fe-spec)
│ ├── stories/EXAMPLE.1.1.md # canonical story format
│ └── epics/ # SO shards (empty until used)
├── templates/legion/ # skeletons seeded into target docs/
├── hooks/hooks.json # global hook config template
├── githooks/pre-push # make scan gate
├── .github/ # copilot-instructions, PR template, lint workflow
├── CLAUDE.md # Claude Code system prompt
├── AGENTS.md # cross-platform mirror
├── GETTING_STARTED.md # first-feature walkthrough
├── ATTRIBUTION.md # MIT credits
├── LICENSE # MIT
└── Makefile # entry point
MIT. See LICENSE for the project license and ATTRIBUTION.md for upstream credits.