# Super Aidlc

> Structured development with design docs, parallel agent builds, TDD enforcement, parallel specialist reviewers, and compound knowledge system. Use for any task beyond a trivial bug fix.

- **Type:** Skill
- **Install:** `agentstack add skill-warren830-super-aidlc-super-aidlc`
- **Verified:** Pending review
- **Seller:** [warren830](https://agentstack.voostack.com/s/warren830)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [warren830](https://github.com/warren830)
- **Source:** https://github.com/warren830/super-aidlc

## Install

```sh
agentstack add skill-warren830-super-aidlc-super-aidlc
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-warren830-super-aidlc-super-aidlc
- Seller: https://agentstack.voostack.com/s/warren830
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.