# SAP — Spec-Driven Architectural Pipeline (A Deep Rethink Based on superpowers · agent + skill + rule three-layer architecture)
> As models grow stronger, the real challenge isn't "can it be done" anymore — it's "can it be done reliably every time." SAP uses three layers of constraints to converge LLM randomness into reproducible engineering delivery, at an acceptable cost. > > Brainstorm-first · Spec-driven · Atomic execution · Five-layer verification > > GitHub: cocacocca/sap
superpowers Is a Giant. SAP Stands on Its Shoulders.
superpowers did something remarkable — it proved AI coding agents can follow structured workflows: brainstorm-first, worktree isolation, TDD red-green cycles, subagent-driven execution.
I've used superpowers extensively. I deeply respect its design philosophy.
But after deep use, I formed one core judgment:
> The stronger the model, the stronger the constraints must be.
This isn't a slogan. Let me explain how I arrived at this.
Core Hypothesis: Why "Stronger Models Need Stronger Constraints"
What Happens When Models Get Stronger
When models were weak, constraints had to be light — leave room for the model to maneuver. superpowers keeps skills under 200 lines for exactly this reason: limited model capacity, heavy constraints would stifle it.
When my primary model upgraded to 1M standard context, the situation reversed:
First change: degrees of freedom explode. The model can process far more information simultaneously, meaning it can "improvise" in far more directions. Within a 1M window, the model can simultaneously consider 10 implementation approaches, 5 architecture styles, 3 naming conventions.
Second change: randomness amplifies. High freedom → different reasoning paths each time → different output. Same request, asked twice, yields two code styles. Asked ten times, ten variations.
Third change: non-reproducibility. High randomness → unpredictable output → cannot reproduce. You ask the model to run the same flow again, it produces entirely different results. During code review you notice "last time it wasn't written this way," but how it was written last time is already lost.
The causal chain:
Model gets stronger → Freedom increases → Randomness increases → Output becomes uncontrollable → Non-reproducible
↑
Strong model + weak constraints = different output every time, quality depends on luck
Why Constraints Lock Down Randomness
Constraints don't limit model capability — they limit model degrees of freedom.
- Agent persona constraint: "You are backend craftsman, you don't write frontend" — eliminates the model's freedom to improvise toward frontend
- Skill workflow constraint: "Five-layer construction: types → data → logic → interface → cross-cutting" — eliminates the model's freedom to choose arbitrary architectures
- Rule project constraint: "Use MySQL + snake_case + soft delete" — eliminates the model's freedom to choose databases and naming
After three layers stack, the model's freedom is compressed into a narrow but deep channel:
No constraints: model freedom ████████████████████ → extreme randomness
One layer: model freedom ████████████ → moderate randomness
Two layers: model freedom ████████ → low randomness
Three layers: model freedom ████ → minimal randomness, approaching deterministic fit
Compressed freedom ≠ compressed capability. The model's reasoning power, code generation ability — these don't change. Only its "improvisation space" narrows to a channel with higher determinism. In this channel, it still thinks deeply, but the direction of thinking is locked onto "the correct track."
Validated in Practice
With three layers of constraints, whether I use a strong model (GLM 5.2) or a slightly weaker one, output stays on track — three-layer constraint stacking locks randomness within acceptable bounds, approaching deterministic fit.
What superpowers Does vs What SAP Changes
| Dimension | superpowers | SAP | Why |
|---|---|---|---|
| Architecture | Single layer: skill | Three layers: agent (persona) + skill (workflow) + rule (constraints) | Stronger models need sharper role separation |
| Code review | Generic reviewer | GAN discriminator — different model cross-reviews | Same model self-defends, different models complement blind spots |
| Project rules | None (skill-embedded discipline) | Explicit rule layer | No constraints → style drift, knowledge doesn't accumulate |
| Skill size | <200 lines (small context constraint) | 500-800 lines (1M context allows) | Strong models handle complete checklists |
| Skill count | ~14 | Designed by workflow, no upper limit | Add what's missing, redesign what's unsatisfactory |
Cost & Efficiency: Why You Don't Need Top-Tier Models
First, Why "Best Below the Best" Can Match the Best
A clarification: GLM 5.2 and Kimi Code 2.7 are the best below the best — in their respective domains (code generation / frontend), they are themselves top-tier, and the gap with Claude / Codex is a gradient, not a cliff.
According to [Artificial Analysis](artificialanalysis ai) coding-index:
- GLM 5.2 closely trails top-tier models in code generation accuracy
- Kimi Code 2.7 excels in frontend/UI scenarios
- DeepSeek-V4-Flash has unique advantages in reasoning chain depth
The gap between them and Claude / Codex is not a cliff — it's a shrinking gradient.
So the question becomes: when the gap is already small, what determines final output quality?
The answer: process discipline.
A feature from requirement to delivery passes through fixed phases: brainstorm → spec → design → decompose → implement → review → document. Each phase has clear inputs, outputs, and check criteria.
Top-tier models excel at "intuition" — they make correct choices under weak constraints. But intuition is unreliable (high randomness) and expensive.
GLM 5.2 / Kimi Code 2.7 / DeepSeek-V4-Flash — these "best below the best" — excel at "execution": their coding ability is already strong, they just need clear processes and checklists to produce high-quality output stably. And they're affordable.
What SAP's three-layer constraints do: replace model intuition with process discipline.
| Phase | Top-tier model relies on | SAP relies on (GLM 5.2 / Kimi / DeepSeek + three layers) |
|---|---|---|
| Brainstorm | Model's own reasoning power | brainstorming skill's structured frameworks (5W2H / fishbone / SCQA) guide reasoning |
| Specification | Model "knows" what to write | spec-writing skill's checklists pin down output item by item |
| Implementation | Model "intuits" correct architecture | backend-implementation skill's five-layer + gate self-checks |
| Code review | Model "spots" issues | Model heterogeneity GAN review — different models complement blind spots |
Conclusion: when a model's own capability is already strong enough, what determines output quality isn't "use a stronger model" — it's "give a strong enough model sufficient process discipline." Process discipline + model heterogeneity ≈ top-tier model intuition, at 1/4 the cost.
Test Data
Primary model combo: GLM 5.2 + Kimi Code 2.7 + DeepSeek-V4-Flash + LongCat-2.0 (Meituan). Tested on single medium-to-large feature development.
A complete /sap run (including brainstorming, discussion, self-review, doc collaboration — all phases) consumes approximately 3-5 million tokens (amortized), producing a complete planning package.
Monthly Cost (China Coding Plans)
| Model | Plan | Monthly Cost |
|---|---|---|
| GLM Max | ~4B tokens/month | ¥375.2 (~$52) |
| Kimi Code | ~1-2B tokens/month | ¥149 (~$21) |
| DeepSeek / LongCat | Pay-per-use | |
| Total | ~¥600/month (<$100) |
Without model heterogeneity (single GLM Max handles everything), monthly cost drops to ~$50.
Cost Gap vs Top-Tier Models
Claude Code and Codex do have coding plans (subscriptions), but their plans scale with usage — heavy development can easily hit $200-$500/month. A single medium-to-large feature running the full SAP workflow (3-5 million tokens) costs 3-5x more with top-tier models compared to the Chinese model combo.
About Proxy Multiplier Rates
API proxies make top-tier models more accessible at lower cost — this is a good thing. It lowers the barrier and benefits more developers.
But there's an issue worth paying attention to: multiplier rates aren't just price discounts — they often come with service differences. Models accessed through multiplier-rate proxies may have different response quality, stability, and concurrency limits compared to direct API access. This isn't about proxies being bad — it's about factoring the multiplier's potential impact into your comparison, especially when putting a proxy-discounted top-tier model next to a directly-connected Chinese model.
For model capability comparison, see Artificial Analysis coding-index rankings. Chinese models like GLM and Kimi are closing the gap with Claude and Codex on coding ability. When the base gap is already small, the service differences from proxy multiplier rates may further narrow or even reverse it.
So my logic is: within a limited budget, use direct, complete, cost-controllable Chinese model combos combined with three-layer constraints, to achieve what top-tier models need several times the budget to do. This isn't "settling for less" — it's "optimizing within constraints."
Why It Gets Cheaper Over Time
Chinese models keep upgrading — stronger capability, same or lower price. And China's AI infrastructure is accelerating: as compute backbones like Huawei Ascend 950 supernodes come online, inference costs will drop further. Subscription plans will evolve in two directions — either more quota or lower prices. Either way, the usable token budget per dollar will be more generous than Claude Code / Codex.
What does this mean? What a top-tier model does in 1 pass, a near-top model with SAP's three-layer constraints might take 2-3 passes to complete — but the cost difference is large enough that you can afford those 2-3 passes and still have budget left for more features. The key metric isn't single-pass efficiency — it's total output per unit budget.
The three-layer framework stays constant, but the models executing within it keep getting stronger and cheaper.
This is SAP's long-term compound interest: framework locks the process, models keep upgrading, costs keep dropping, efficiency keeps rising.
Three-Layer Architecture: Why Three, Not Two or Four
One Layer (superpowers' Choice)
superpowers earning widespread adoption is itself proof that AI coding agents can follow structured workflows.
But as model capabilities continued upgrading, the relative constraint strength weakened. I observed three trends:
- Role boundary blurring: A single agent handling both brainstorming and implementation had no clear switching point between thinking modes
- Project conventions not persisting: Discipline embedded in skills couldn't distinguish "what this project uses" from "general best practices"
- Process and constraints coupled: Skills mixed "how to do" with "what not to do" — changing constraints meant touching process, and vice versa
These aren't superpowers' design flaws — they're the natural consequence of models getting stronger while single-layer constraint strength stayed the same. This observation is exactly what drove me to rethink the architecture.
Two Layers (skill + rule)
Adding the rule layer solved the project convention problem — RULE_DB declares "use MySQL," agent follows. Process and constraints were decoupled.
But the role boundary issue remained: without an agent persona layer, the one executing spec-writing and the one executing code-audit were "the same character." Brainstorming's divergence and review's convergence are conflicting modes — without explicit identity switching, the model transitions模糊ly between them.
Three Layers Was Enough
Adding the agent persona layer gave each phase a clear role identity:
- brainstorm-agent: divergent thinking, exploring possibilities, forbidden from writing code
- spec-coordinator: convergent thinking, making fuzzy precise, forbidden from writing code
- backend-craftsman: execution thinking, implementing per spec, forbidden from crossing boundaries
- quality-evaluator: skeptical thinking,专门 finding problems, forbidden from fixing (only reports)
Each layer's responsibility:
┌─────────────────────────────────────────────────────┐
│ Agent (Persona) │
│ "Who am I? What are my boundaries?" │
│ → Identity, responsibilities, gates, iron laws │
│ → Defines role, forbids boundary crossing │
├─────────────────────────────────────────────────────┤
│ Skill (Workflow) │
│ "How do I do this specific task?" │
│ → Step-by-step methodology, checklists, templates │
│ → Defines process, reusable across projects │
├─────────────────────────────────────────────────────┤
│ Rule (Constraint) │
│ "What can I NOT do in this project?" │
│ → Project conventions, tech stack, naming, style │
│ → Defines constraints, project-specific │
└─────────────────────────────────────────────────────┘
Why not four layers? I tried splitting "communication protocol" into a separate layer, but it's fundamentally part of the agent persona (each agent knows who to hand off to and how). Separating it added complexity without value. Three layers is sufficient and minimal.
Key Distinctions
Skills contain no persona — multiple agents share the same skill. backend-craftsman and frontend-craftsman both use TDD red-green cycles, but load different rules.
Skills contain no constraints — the same backend-implementation skill behaves differently under different RULE_DB.md (MySQL vs PostgreSQL).
Rules contain no process — RULE_API.md declares "RESTful + URL versioning + error code format," it doesn't teach you how to write APIs (that's a skill's job).
How Three Layers Collaborate
Agent loads skill to execute workflow, while following rule constraints
Example: backend-craftsman (agent persona)
+ backend-implementation (skill workflow: five-layer construction)
+ RULE_DB.md (rule constraint: MySQL + snake_case + soft delete)
= implement backend features per project conventions
The effect of three-layer constraint stacking: regardless of using a strong or slightly weaker model, output stays within the three-layer framework, barely drifting — solving the problem of high randomness and non-reproducible generation in LLMs.
> Some might ask: aren't three layers too heavy? Won't they confuse the model? > > This framework has been repeatedly validated in real projects. If three layers of constraints actually confused the model and degraded output quality, I wouldn't publish it — let alone use it for daily development. The opposite happened: with three layers, output quality and reproducibility improved significantly. That's exactly why I'm sharing this idea — because it actually works.
Skill Definition: Why "Workflow" Not "Ability"
What a Skill Is Not
Many people understand skill as "ability" — "the model learned a skill." This is a misunderstanding.
In SAP, skill is not the model's capability. The model's code generation, reasoning, language understanding — these are built-in. Skill doesn't manage them and shouldn't.
What a Skill Is
Skill is complete documentation of a specific workflow.
It tells the agent: from start to finish, what to do at every step, what to check, what to produce. It doesn't teach the model "how to write code" (the model can write) — it teaches the model "what process to follow when writing code" (process is human engineering experience).
Example: backend-implementation skill doesn't teach the model "what TDD is" (the model knows) — it mandates that the five-step cycle (write failing test → verify failure → minimal implementation → verify pass → commit) must execute, and testing happens immediately after each construction layer.
What a Skill Contains
| Content | How specific |
|---|---|
| Step-by-step process | Phase 1 → Phase 2 → ... → Phase N, each with clear inputs/outputs |
| Checklists | Not "ensure quality," but "V1 Lint zero errors / V2 Typecheck zero type errors / V3 Build succeeds" |
| Output templates | Not "write a document," but specific markdown structure (field names, format, examples) |
| Gate checks | Not "good enough, submit," but item-by-item self-check table (binary pass/fail) |
| Anti-pattern tables | Not "be careful," but "when this error appears, do this" (specific fix) |
What a Skill Does NOT Contain
- No persona identity (that's agent's job) — skill doesn't say "I am backend craftsman"
- No project constraints (that's rule's job) — skill doesn't say "use MySQL"
- No communication protocol (that's agent's job) — skill doesn't say "report to whom after completion"
Why Skills Can Be 500-800 Lines
superpowers keeps them under 200 — optimal for small context, where context is precious and must be concise.
But at 1M context, conciseness becomes a disadvantage:
| Constraint | Small Context | 1M Context |
|---|---|---|
| Skill size | <200 lines | 500-800 lines |
| Simultaneous load | 1-2 | 5-7 |
| Detail level | Summary + pointers | Full checklists + templates + examples |
SAP removes line limits. Each skill contains complete checklists, templates, examples — no "see references/" indirection. When an agent loads a skill, it gets a complete manual ready for immediate execution, not an index that "requires looking elsewhere."
How Skills Evolve
Designed by workflow, theoretically unlimited. Currently covering 8 scenarios across complete chains.
- New scenario → design new skill
- Unsatisfactory flow → redesign skill
- Gap between two scenarios → add a skill
Skill count is a snapshot of workflow coverage, not a target value.
Core Design Philosophy: Leverage LLM Strengths + Weaknesses
1M context windows make specialization possible. LLM weaknesses make specialization necessary.
Leverage Strengths
| Strength | How SAP Uses It |
|---|---|
| Deep reasoning | Brainstorm agent explores multiple paths before committing |
| Context retention | 1M window holds multiple skills + rules simultaneously |
| Multi-perspective analysis | Six thinking hats, 5Why, fishbone — structured frameworks |
Compensate Weaknesses
| Weakness | How SAP Compensates |
|---|---|
| Context overflow | Multi-agent isolation — each agent loads only what it needs |
| Self-defense in review | Model heterogeneity — reviewer uses different model than implementer |
| No project memory | Rule layer — explicit constraints persist across sessions |
| Inconsistent output | Structured communication protocol — machine-readable handoff |
| High randomness, non-reproducible | Three-layer constraint stacking — compresses freedom into a narrow but deep channel |
Communication Protocol Between Agents
Agents communicate through structured handoff messages. Not human chat — machine-readable protocol.
[PLANNING_COMPLETE] feature_id=user-auth-v2
[PLAN_PACKAGE] sap/user-auth-v2/
[CONTENTS] spec.md, tasks.md, checklist.md, dag.md
[GATE_RESULT] G1-G8 all pass
[NEXT] controller dispatch per DAG
[DISPATCH] task_id=T-001
[TO] sap:backend-craftsman
[REQ] goal/design_ref/criteria/packages
[COMPLETE] task_id=T-001
[TEST] 42 passed, 0 failed
[GATE] V1-V5 + S1-S3 pass
Why structured protocol: machine-parseable, audit trail, recoverable after context compaction.
Model Heterogeneity (GAN Discriminator)
Generator and Discriminator should not share the same model.
Same model writing and reviewing code → "understands intent, lets it pass" + shared blind spots + self-justification.
| Role | Model | Why |
|---|---|---|
| Brainstorm | DeepSeek-V4-Flash | Strong reasoning chain |
| Backend | GLM 5.2 | Code generation accuracy |
| Frontend | Kimi Code 2.7 | Frontend-specific patterns |
| Review | Different from implementer | GAN adversarial review |
Not "better models" — different bias patterns catching each other's blind spots.
Workflow Overview
User Request
↓
Main agent reads bootstrap (auto-injected at SessionStart)
↓
P0 Brainstorm → P0.5 Spec → P0.85 Design → P1 Decompose
↓ (planning package ready)
Main agent → controller mode
↓
P2 Dispatch craftsmen (model heterogeneity) → P3 Review QE (different model) → P4 Docs
Output Path
sap/{feature-id}/
├── brainstorm.md # P0
├── spec.md # P0.5
├── tasks.md # P0.5
├── checklist.md # P0.5
├── design.md # P0.85 (complex only)
├── arch/ # P0.85 ADR
└── dag.md # P1
Project Structure
sap/
├── .zcode-plugin/ .claude-plugin/ .codex-plugin/ .opencode/
├── .mcp.json # MCP server config
├── /lsp # LSP integration
├── hooks/ # SessionStart injection (multi-platform)
├── commands/ # /sap /brainstorm /audit /rules
├── agents/ # agent personas
├── skills/ # designed by workflow, no upper limit
└── rules/ # project constraint templates (git-ignored)
About Model Selection & Open Source
Model Selection
The model combo mentioned in this article (GLM 5.2 / Kimi Code 2.7 / DeepSeek-V4-Flash / LongCat-2.0) is my personal choice after weighing capability against cost. It doesn't mean these are the only or optimal options. I've tried mainstream models on the market — including MiMo, MiniMax, and others — and the ones I selected are those that hold up under daily development in both capability and cost.
If you think "these models aren't good enough," that's a completely understandable perspective. Honestly, if someone were willing to sponsor me unlimited access to Claude Code Fable 5 and Codex GPT-5.5 xHigh, I'd happily use top-tier models to fully unleash what SAP can do :)
But the reality is: not everyone can afford top-tier models long-term. SAP's value is — within your affordable model budget, pulling output quality as high as possible.
About Open Source
This repository currently shares design philosophy only, not the plugin implementation code.
The reason is simple: I'm not sure if this idea is truly valuable yet. If people resonate with it — and stars indicate that — I'll open-source the full plugin code. If not enough people connect with the idea for now, I'll keep absorbing new insights and evolving — I'll share the code when I've figured it out.
No rush. Ideas need validation, not aggressive promotion.
Contact
If you have thoughts to discuss, feel free to reach out via email or on GitHub.