Super Aidlc

Super-AIDLC

The user wants to: $ARGUMENTS

Flags

Super-AIDLC supports these flags in the user's input:

| Flag | Effect | |------|--------| | --dry-run or --preview | Preview the pipeline without executing | | --light | Force Light complexity (skip design, minimal process) | | --medium | Force Medium complexity | | --heavy | Force Heavy complexity (full design + parallel builds) | | --skip-review | Skip two-stage review (only for trusted fixes like typos) | | --skip-tests | Skip TDD requirement (only for non-code changes like docs/config) | | --no-security | Disable security baseline | | --auto | After design approval, auto-run construction + operations with fresh subagent isolation | | --lang=zh | Generate all artifacts in Chinese (中文) | | --lang=en | Generate all artifacts in English (default) | | --lang=ja | Generate all artifacts in Japanese (日本語) | | --lang=ko | Generate all artifacts in Korean (한국어) |

Override Safety

Complexity overrides (--light, --medium, --heavy) bypass auto-detection. Use when:

• Auto-detection chose wrong (e.g., "simple" feature that actually needs design)
• You want minimal process for a well-understood change (--light)
• You want full rigor for something that looks simple but has risk (--heavy)

--skip-review is an escape hatch for trusted fixes (typos, single-line corrections, doc-only changes). Note the skip in the build log with the reason.

--skip-tests is an explicit Iron Law bypass for the TDD rule in skills/tdd/. The default path enforces TDD. Use --skip-tests only for:

• Documentation-only changes
• Configuration that cannot meaningfully be unit-tested
• Throwaway prototypes (tell the user; offer a follow-up to TDD-ify if it lives)
• Generated code

When --skip-tests is used, you MUST log the bypass reason in build-log.md under an "Iron Law Bypasses" section (template in phases/construction.md Step 8). Never skip both --skip-tests and --skip-review simultaneously.

Red Flags — STOP, You're Rationalizing

Agents are prone to shortcuts. Before starting a task, or before claiming work is done, check yourself against these thoughts:

| Thought | Reality | |---------|---------| | "This is just a simple question" | Questions are tasks. Check for relevant skills. | | "Let me explore the codebase first" | Skills tell you HOW to explore. Load the skill first. | | "I know what the code should do" | Read it anyway. Evidence > assumption. | | "I'll add tests later" | Tests added later prove nothing. See skills/tdd/. | | "Should work now" / "Looks correct" | Run verification in this message. See skills/verify/. | | "Linter passed, build probably works" | Linter ≠ compiler. Run the build. | | "Agent reported success" | Verify independently — check the diff. | | "The skill is overkill for this" | If the skill applies, use it. | | "Just this once" / "This is different because..." | No exceptions. |

If any thought above matches what you're about to do: STOP and re-read the relevant skill.

Iron Law: Violating the letter of this rule is violating the spirit of this rule.

Language Selection

All generated artifacts (design docs, build logs, questions, review reports, QA reports, PR descriptions) use a single language determined at session start.

Detection Priority (first match wins)

1. Explicit flag: --lang=zh in the user's input → use that language.
2. User's input language: If the user wrote their task description in Chinese → use Chinese. If in Japanese → use Japanese. Match the language the user is speaking.
3. Project convention: If aidlc-docs/ contains prior docs in a specific language → follow that language for consistency.
4. Default: English.

What This Affects

| Artifact | Language Follows | |----------|-----------------| | Questions to user | Session language | | Design document (aidlc-docs/*/design.md) | Session language | | Build log (aidlc-docs/*/build-log.md) | Session language | | Error/Rescue Map | Session language (but error names stay in English for grep-ability) | | Review reports (spec + quality) | Session language | | QA reports | Session language | | PR title and description | Session language | | Commit messages | English always (convention for git) | | Code comments | English always (convention for code) | | Variable/function names | English always (convention for code) |

What This Does NOT Affect

Code is always in English. Variable names, function names, class names, comments in code -- all English. This is a universal coding convention. Only human-facing documents follow the session language.

Propagation to Subagents

When dispatching any subagent (builder, reviewer, researcher, architect, debugger, QA), inject the language instruction:

Session language: {language}
Write all human-facing output (reports, questions, explanations) in {language}.
Code, variable names, and commit messages remain in English.

This ensures all agents produce consistent output. A Chinese design doc followed by an English review report is confusing -- all artifacts must use the same language.

Display at Session Start

After detecting the language, display:

Language: {language} {flag emoji}

as part of the session status line. If the user wants to change it mid-session, they can say "switch to English" or "切换到中文".

Dry Run Mode

If the user's input contains --dry-run or --preview, do NOT execute anything. Instead, display a preview of what Super-AIDLC would do:

Super-AIDLC Dry Run
Task: {1-line summary}
Complexity: {Light / Medium / Heavy}
Workspace: {Greenfield / Brownfield}
Language: {English / 中文 / 日本語 / 한국어}

Pipeline:
  {Light: TDD build → review → auto-verify}
  {Medium: Questions (~N groups) → design doc → parallel TDD build → 2-stage review → auto-verify}
  {Heavy: Reframe → questions (~N groups) → full design + independent design review → parallel TDD in worktrees → 2-stage review → coverage audit → auto-verify}

Estimated units: {N} ({M} parallel, {K} sequential)
Artifacts: aidlc-docs/{date}-{slug}/design.md, build-log.md
Security baseline: {enabled / disabled}

To proceed: re-run without --dry-run

Then STOP. Do not proceed to any phase.

Iron Laws

These five rules are non-negotiable. Detail lives in the referenced files.

1. No production code without a failing test first -- see rules/tdd.md
2. No fixes without root-cause investigation first -- see agents/debugger.md
3. No completion claims without fresh verification evidence -- see guards/verification.md
4. No shipping without all-green verification loop -- tests, build, and lint must all pass. Failures are auto-fixed up to 3 times.
5. No user input passed unsanitized to shell, filesystem, or templates -- see extensions/security-baseline.md. Default on. Shell injection, path traversal, and unbounded buffers are caught by the quality reviewer.

Overconfidence Prevention

Read rules/overconfidence-prevention.md at the start of every session. Agents routinely skip steps they consider "unnecessary" -- this file prevents that. Before completing any phase, run the self-check protocol from that file.

Governance Model

Research shows the #1 problem with AI coding is not capability -- it is governance. Super-AIDLC implements the VPC Principle (Verdict-Permission-Boundary Control):

| VPC Layer | Super-AIDLC Implementation | |-----------|---------------------------| | Verdicts (non-negotiable decisions) | Iron Laws -- TDD, root-cause investigation, verification, security baseline | | Permissions (where AI can operate) | Complexity routing, flags (--skip-review, --skip-tests), user approval gates | | Boundary Control (automated enforcement) | Guards (careful, freeze, verification), two-stage review, auto-verification loop |

The human defines the laws. The AI executes within those laws. When the AI wants to deviate, it asks -- it does not decide.

Three Beliefs

1. Repository is the system of record -- if a decision is not written to a file, it does not exist.
2. Mechanical enforcement over documentation -- prefer a lint rule over a comment, a test over a design-doc paragraph.
3. Design before code, review before merge -- no exceptions for Medium/Heavy tasks.

What Makes This Different From Plan Mode

If you skip any of these, you are just doing plan mode. The whole point is these 9 things:

1. Optional brainstorm phase -- explore requirements before committing to design. See phases/brainstorm.md.
2. Ask structured questions BEFORE designing -- not open-ended; with options and recommendations.
3. Create design documents BEFORE code -- actual .md files with architecture, error maps, diagrams.
4. Parallel research agents -- Researcher + Learnings Researcher + Git History Analyzer + Best Practices Researcher gather context simultaneously.
5. Three-strategy subagent dispatch -- auto-selects Inline (1-2 units), Serial (dependencies), or Parallel (independent). Parallel uses worktree-first with background-fallback. Per-unit self-check and task tracking.
6. Parallel specialist reviewers -- correctness, security, performance, and adversarial reviewers run in parallel with confidence gating.
7. Create persistent artifacts -- aidlc-docs/ that accumulate across sessions.
8. Auto-verification loop -- tests/build/lint are run automatically; failures trigger the debugger agent and re-verify until all green or 3 iterations.
9. Compound knowledge system -- /super-aidlc:compound extracts structured solutions into aidlc-docs/solutions/ for future searchability. /super-aidlc:compound-refresh maintains knowledge base quality.

Step 1: Detect Workspace

Before anything else, determine workspace type:

Greenfield -- no existing source code, no aidlc-docs/.

• Will need harness setup (test runner, linter, CLAUDE.md).

Brownfield -- existing code.

• Scan: aidlc-docs/ for prior design docs and build logs.
• Scan: .kiro/specs/ for existing Kiro specs (if present).
• Scan: CLAUDE.md, README.md, recent git log --oneline -10.
• Reference prior decisions and conventions throughout the session.

Cross-Session Learning (Three-Layer Knowledge System)

Super-AIDLC v4 uses a three-layer knowledge system, searched in this order:

Layer 1: Conventions (aidlc-docs/patterns.md)

• Distilled cross-task conventions (50 lines max).
• Read FIRST by the Researcher. Contains conventions, anti-patterns, stack decisions.

Layer 2: Structured Solutions (aidlc-docs/solutions/)

• Structured knowledge base with YAML frontmatter for searchability.
• Created by /super-aidlc:compound after solving non-trivial problems.
• Organized by category: runtime-issues/, patterns/, security-issues/, etc.
• Searched by module, component, tags. Stale docs deprioritized.
• Maintained by /super-aidlc:compound-refresh (Keep/Update/Consolidate/Replace/Delete).

Layer 3: Build Logs (aidlc-docs/*/build-log.md)

• Per-session history with summary sections for quick scanning.
• Select 3 most relevant by task similarity (not recency).
• Extract: Issues Encountered, Decisions Made, Alternatives Considered.

Layer 2b: Global Solutions (~/.aidlc/global-solutions/)

• Cross-project knowledge shared across all your projects.
• Created by /super-aidlc:compound when a solution is language/tool-generic.
• Lower priority than project-local -- fills gaps when no local match.

Search process:

1. Read aidlc-docs/patterns.md (Layer 1 -- conventions).
2. Search aidlc-docs/solutions/ frontmatter by module/component/tags (Layer 2 -- project knowledge). Deep-read top 3 matches.
3. Search ~/.aidlc/global-solutions/ if Layer 2 has Build / Build only}

Ready? (y/n)

Wait for confirmation.

## Step 3: Execute

**Light**: Read `phases/construction.md` and execute.
**Medium/Heavy**: Read `phases/inception.md` and execute. It will tell you when to proceed to construction.
**Heavy with high ambiguity**: If the task description is vague ("build something like...", "I want to improve..."), suggest brainstorm first: "This task has high ambiguity. Want to run a brainstorm phase first to clarify requirements? (y/n)". If yes, read `phases/brainstorm.md` and execute. Its output feeds directly into inception.

### Auto Mode (`--auto`)

When `--auto` is set and inception completes (design approved), do NOT read `phases/construction.md` inline. Instead, dispatch the full construction + operations pipeline as fresh subagents.

**Construction (fresh subagent):**

Agent( prompt: " --- Design Document ---

--- Project Context ---

--- Rules ---

--- Config --- Language: {session language} Complexity: {complexity} Auto mode: true — proceed without asking user for confirmation. Write all results to aidlc-docs/{date}-{slug}/build-log.md.", description: "Auto construction: {feature name}" )

**Gate check (inline — read build log, verify all green):**

1. All units DONE or DONE_WITH_CONCERNS?
2. Spec review PASS?
3. Quality review PASS?
4. Verification loop all green?

- ALL PASS → output status report, proceed to operations.
- ANY FAIL → output problem details, wait for user input.

[AUTO] Construction complete Units: {N/N} DONE | Tests: {N} passing | Spec: PASS | Quality: PASS Proceeding to operations...

If problems found:

[AUTO] Construction needs attention {problem details} Options: (A) Retry (B) Skip and proceed (C) Abort auto, switch to interactive

**Operations (fresh subagent):**

Agent( prompt: " --- Build Results ---

--- Config --- Auto mode: true — auto-commit on all-green, do not ask for ship confirmation. Append verification results to build-log.md.", description: "Auto operations: {feature name}" )

**Final report:**

- ALL GREEN → output report, auto-compound if score >= 3, ask about push/PR (push is irreversible — always ask).
- FAIL → output errors, wait for user.

[AUTO] All complete Verification: PASS | Tests: {N} passing | Commit: {sha} Compound score: {N} → {auto-compounding / suggested / skipped} Push and create PR? (y/n)

## Interruption Protocol

If the user changes requirements during the Construction phase (e.g., "wait, I want to change X" or "actually, skip Y"):

1. **Assess impact** -- which units are affected?
   - Only unstarted units? → Update the design doc, continue. No disruption.
   - Currently building units? → Let the in-progress builders finish their current RED-GREEN cycle, then stop. Discard incomplete work in those worktrees.
   - Already completed and reviewed units? → Mark them as "needs modification" in the build log. Complete the current batch first, then rework in a follow-up pass.

2. **Update the design doc** -- record the change in the Decisions Log:
   ```
   | Mid-build change | {what changed} | {user requested at construction step N} |
   ```

3. **Re-assess complexity** -- if the change fundamentally alters scope (e.g., "actually make this a microservice instead of a monolith"), STOP construction and go back to inception. This is rare but important.

4. **Resume construction** with the updated design. Builders that were not affected continue as normal.

The key principle: **never discard work that is already reviewed and passing**. Modify it in a follow-up pass instead.

## Safety Note

If the user runs destructive commands (rm -rf, git reset --hard, force push, DROP TABLE, etc.), load `guards/careful.md` and follow its protocol before executing.

## QA Routing

If the project has a UI (web app, desktop app, etc.), suggest running `phases/operations.md` QA workflow after construction completes. This is optional but recommended.

## Output Routing

Specs and design artifacts go to different locations depending on the platform:

- **Kiro projects** (`.kiro/` directory exists): write specs to `.kiro/specs/{feature}/` AND `aidlc-doc

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [warren830](https://github.com/warren830)
- **Source:** [warren830/super-aidlc](https://github.com/warren830/super-aidlc)
- **License:** MIT

Install and usage instructions live in the source repository linked above.