English · 中文

ai-coding-workflow ^V3.1.1

SDD Pinple Workflow — Make AI work like a real senior engineer.

This is more than a workflow — it's a portable, business-agnostic "cognitive operating system" for an AI engineer. Drop it into any repository, feed one prompt to your AI, and it bootstraps a complete collaboration system: an AI that does its homework before acting, stays within guardrails, remembers its lessons, and grows with your project.

The goal isn't "let AI write a few lines of code for you" — it's "give AI the working style, judgment, and growth of a seasoned engineer".

Why · Quick Start · Highlights · Architecture · Docs

---

🆕 V3.1.1: Companion toolchain skills vendored (2026-09-19)

After cloning this repo on a fresh machine, the workflow's own tooling should ship with it rather than live on one person's laptop. Three additions: ai-tool-migrator (cross-tool migration of Skills/MCP/Agents/Memory between Claude Code / Codex / ZCode / Cursor / OpenCode / WorkBuddy / dsh — the dependency MULTI-TOOL-AUTHORITY.md references now lives in-package), skillhub-ship (zero-trap publishing of local skills to SkillHub), deepseek-harness-installer (one-shot dsh install & verification). 33 → 36 skills.

🆕 V3.1: Capability expansion & cross-machine migration (2026-09)

V3.0 converged the process; V3.1 ships the methodology skills distilled from real usage — and answers "how do I take this whole workflow to another machine?"

• Workflow migrator (workflow-migrator) ⭐: migrate this seed repo to a fresh computer / new tool environment. Read-only inventory first (scan_migration.py conflict matrix: new / identical / differs), then one of two target shapes — plain per-tool copy, or ~/.agents single-source-of-truth with junction shells. Append-only, migration report with rollback list.
• Method-review trio: grill-method attacks how you're working (is this the optimal route?), doubt-driven-development adversarially reviews non-trivial decisions in fresh context before they harden, idea-vetting vets unproven ideas against prior art before you invest.
• Craft skills: code-simplification (reduce complexity, behavior preserved), memory-find (keyword recall across memory & knowledge assets), glossary-builder (extract enum/synonym maps into .notes/foundation/glossary.md), context-stacking (three-step deep learning, complements the comprehension ledger).
• Field-tested upgrades, sanitized: api-doc-generator's five hard rules (encoding/annotation/gateway-path/dedup — distilled from real YApi incidents) and security conventions (identity-from-context, IDOR checks) now ride along in shared-references/.

---

🆕 V3.0: Convergence & Comprehension (2026-09)

V1/V2 made AI reliable; V3.0 fixes two deeper problems: the workflow itself got too heavy, and humans stopped understanding what AI ships.

• Expert-package workflow: 20+ pipeline skills collapsed into one entry point with S/M/L sizing — small tasks skip the ceremony entirely. See EXPERT-PACKAGE-PATTERN.md.
• Comprehension ledger: boundary Q&A before sign-off, a human-facing handover trio after verify, and Leitner-box spaced review — turning "AI wrote it, I never understood it" into a repayable debt. See skills/comprehension-ledger/.
• Workflow audit & slim (audit-slim): evidence-based Keep/Merge/Delete for resident rules & skills, plus Step 0 post-upgrade consistency inspection (4 layers: links / references / command paths / factual claims) — because "rebuilt the new" never automatically means "cleaned the old".
• Single source of truth across tools: ~/.agents/ as the one authority; per-tool dirs become junction shells. See MULTI-TOOL-AUTHORITY.md.
• Context budget: rules split core/methodology (-60% resident injection); plans delivered as a one-pager + appendices.
• Field-tested on a real L-level requirement: discovered ~70% was already implemented on a legacy branch before writing a line; sign-off gate held (zero production code without approval). Full story: EVOLUTION-V3.md.

---

💡 Why you need it

Today's AI coding assistants are powerful, but everyone who's used one has hit the same walls:

Pain point	You've definitely experienced	What this workflow does about it
AI forgets	A new conversation = total amnesia; you re-explain the project every time	Memory system + knowledge assets + task persistence — context survives across sessions
AI hallucinates	Invents classes and methods that don't exist; acts after reading just one file	Four-questions-before-acting + Spec-first + automated fact-verification
AI goes off the rails	Loops endlessly breaking code, or over-engineers far beyond the requirement	Circuit-breaker protocol + reversibility tiers + context-isolated sub-agents
AI never grows	Makes the same mistake again; ignores yesterday's correction	Compound Learning loop — every correction becomes a memory/rule; it gets to know your project better over time

This is not yet another "prompt template". It's a constrained, self-reflective, evolvable cognitive OS — it encodes a senior engineer's working style (research first, respect boundaries, retrospect, accumulate experience) into muscle memory the AI follows at every step.

---

🚀 30-second quick start

# 1. Drop this repo into your project as a subdirectory, or just clone it
git clone https://github.com/<your-name>/ai-coding-workflow.git

2. Open BOOTSTRAP.md and copy the "bootstrap prompt" inside.

3. Paste it into your AI IDE (Cursor / Claude Code / any agent that supports custom rules).

That's it. The AI will automatically: analyze your repo → deploy the workflow files → fill in placeholders → generate a first draft of .notes/ knowledge assets → self-verify.

Got a new machine? Clone this repo there, then tell the AI: "use skills/workflow-migrator to install this workflow into my environment on this machine" — it inventories conflicts read-only, then migrates via plain per-tool copy or ~/.agents single-source-of-truth, append-only with a rollback-capable report. See skills/workflow-migrator.

Want to deploy manually or understand what each file does? See docs/DEPLOYMENT.md.

---

✨ What makes it special

This workflow wasn't designed on a whim — it was forged through countless iterations on real enterprise-grade production projects. A few designs that genuinely matter:

🧭 Four Questions Before Acting — give AI an "instinct"

Before touching anything, the AI auto-checks four things: recall past lessons → route to the right skill → consult project knowledge → verify the code entity actually exists. This turns "AI guessing" into "AI doing its homework first".

🔄 EDD (Evaluation-Driven Development) — closed-loop iteration

A complete measurement closed loop: Practice → Collection → Consumption → Decision → Practice. Four automated Hooks (SessionStart/Stop/SessionEnd/PreCompact) power a self-healing eval pipeline — L2 Agent-as-Judge gates every session end, SessionEnd auto-collects metadata, PreCompact preserves critical decisions across context compaction.

🧠 Context Engineering — three-layer architecture

Hot (~3000 tokens, always-on): CLAUDE.md + alwaysApply rules. Warm (on-demand): Skills + references, loaded by trigger. Cold (on-demand retrieval): .notes/ docs + historical logs. Proactive delegation decision tree saves tokens without losing capability.

🛡️ 12 Iron Laws + L2 Judge — hard gate enforcement

Stop Hook prompts a structured L2 Agent-as-Judge ({ok, violations, reason}) to check every code change against 12 iron laws — exceptions, SQL injection, identity forgery, tenant isolation, credential leaks, idempotency, resource leaks, transaction abuse, IDOR, thread context, and scheduled-task safety. ok=false hard-blocks the session from ending.

📐 Spec-first + Test-cases-first — kill defects before writing code

Complex tasks are not allowed to start with code. First produce a fact-verified technical spec, then run path verification, consistency checks, pre-mortem reasoning, and multi-perspective review. The companion "test-cases-first" philosophy — write stable behavioral contracts at design time, only run regressions while coding, and materialize test classes after the code is finalized — eliminates the chronic pain of "tests churning along with the implementation".

🧠 Memory that "assists decisions" — not just remembering, but actively avoiding

Many AI tools now have memory, but most stop at "remembering your preferences". This workflow's memory goes further — it actively recalls and participates in decisions before every action.

• Categorized accumulation: preference / feedback / insight / reference — four types, each with a clear role
• Active recall (Q0 of the four questions): before acting, scan the memory index; load any relevant lesson and avoid the mistake before it happens, instead of realizing it afterward
• Promotion mechanism: every memory carries a "why" so edge cases can be judged; critical lessons get promoted to enforced rules
• Memory hygiene: auto-detect staleness, merge duplicates, cap capacity — memory never devolves into clutter

In one line: other tools' memory is "the AI remembers what you said"; here, memory is "before doing anything, the AI first recalls where it tripped on this kind of task before".

🔄 Compound Learning — never trip on the same stone twice

Every correction triggers a loop of "root-cause analysis → memory-promotion evaluation → distill into a memory or rule". The longer you use it, the better it understands your project; mistakes turn into reusable assets — exactly what separates a senior engineer from a newcomer: experience accumulates.

🛡️ Circuit-breaker protocol — give AI a "fuse"

Three failed attempts in a row force a stop-and-rethink. An explicit progress counter + a five-level action ladder root out both "AI repeatedly breaking code" and "search-bombing" dead loops.

🧩 Expert package + pluggable skills — both a constitution and a toolbox (V3.0 restructured)

From the "constitution" (AGENTS.md) to routing to skills to the feedback loop — cleanly layered, each with its job. The 36 skills are trimmable on demand, covering the full dev lifecycle from unit testing and code review to architecture guarding, method review, and knowledge distillation.

🔌 Tool-agnostic — bound to no IDE, bound to no business

Designed entirely with neutral conventions and placeholders — runs on Cursor, Claude Code, or any agent. All business coupling has been stripped out, so it adapts to any language and any domain.

---

📐 The five-layer architecture

┌──────────────────────────────────────────────────────────────────┐
│  Layer 5 · EDD & Automation      Hooks · Cron · eval pipeline     │  ← self-healing
├──────────────────────────────────────────────────────────────────┤
│  Layer 4 · Loop & Persistence    task persistence · breaker ·      │  ← gets smarter
│                                  observation · memory              │     over time
├──────────────────────────────────────────────────────────────────┤
│  Layer 3 · Capabilities          36 Skills · sub-agents · orch.  │  ← the toolbox
├──────────────────────────────────────────────────────────────────┤
│  Layer 2 · Routing & Decision    skill routing · knowledge        │  ← the dispatcher
│                                  routing · complexity triage      │
├──────────────────────────────────────────────────────────────────┤
│  Layer 1 · Constitution          AGENTS.md · coding standards ·    │  ← the constitution
│                                  behavioral boundaries            │
└──────────────────────────────────────────────────────────────────┘

Full design philosophy and data flow: ai-coding-workflow-architecture.md.

---

📂 Repository structure

ai-coding-workflow/
├── README.md                              # This file — English landing page
├── README.zh-CN.md                        # Chinese landing page
├── BOOTSTRAP.md                           # ⭐ One-shot bootstrap prompt
├── ai-coding-workflow-architecture.md     # Four-layer architecture guide
├── AGENTS.md                              # Agent entry (identity/principles/boundaries/loop)
├── LICENSE                                # MIT
├── docs/
│   └── DEPLOYMENT.md                          # Manual deploy guide + trimming + checklist
│
├── rules/                                 # Constitution layer (20 rules)
│   ├── ...                                    # (see full list in architecture doc)
│
├── skills/                                # Capability layer (20+ skills, each with SKILL.md)
│   ├── ...                                    # (see full list in architecture doc)
│
└── templates/                             # Scaffolding templates
    ├── .notes-scaffold.md                     # .notes knowledge-asset directory structure
    ├── eval-log-template.md                   # Eval log format template
    ├── memory-scaffold.md                     # Memory index skeleton template
    └── PLATFORM-ADAPTER-template.md           # Platform adapter template (Claude Code/Cursor)

---

📖 Documentation

I want to…	Go here
Start right now	BOOTSTRAP.md — copy the prompt, feed it to your AI
Deploy manually / trim on demand	docs/DEPLOYMENT.md
Understand the design	ai-coding-workflow-architecture.md
Read the AI's "constitution"	AGENTS.md

---

🤝 Contributing & extending

The core design philosophy of this workflow is evolvability — fork it, trim it, extend it.

• Add a rule: create rules/{semantic-name}.md
• Add a skill: use skills/skill-creator to scaffold a new skill
• Add knowledge: distill into .notes/ across the Foundation / Patterns / Analysis layers

Follow the "knowledge-routing decision tree" in AGENTS.md to decide which layer new knowledge belongs to.

---

📄 License

MIT © crayon

This is a system I forged through countless iterations on real projects, distilling all my thinking on one question: how do we make AI not just "able to write code", but actually work like a senior engineer — researching, judging, respecting boundaries, retrospecting, and growing. Now it's open-source. I hope it helps everyone who wants to take AI Coding seriously. Enjoy. 🚀