How This Site Was Built

Why This Page Exists

This page is a working example of AI-native practices. Every spec in this repo, every commit, every gate decision is an artifact of the SDD methodology described here.

Adapted from GeekByte's structured agentic development pipeline, developed by Grant Howe.

The SDD Pipeline

Every change to this site flows through the same nine-node pipeline: five stages and four gate checkpoints, from first requirement to production.

Figure 1: The SDD Pipeline — PM-Spec through Production

PM-Spec. Natural-language requirements become a structured Feature Spec with acceptance criteria, dependencies, and a tier recommendation — AI-assisted, human-approved at Spec Gate.

Spec Gate. Rob approves the spec — or, for Critical-tier work, brings in an external second reviewer. Open questions are resolved here, before architecture or implementation begins.

Architect-Review. The spec is validated against the site's existing patterns and architecture. Security-sensitive specs trigger an additional penetration-tester review at this stage.

Arch Gate. Formal approval to proceed to implementation. Blocking findings from Architect-Review must be absorbed into the spec before this gate closes.

Implementer-Tester. The implementation stage: frontend-developer builds, qa-expert defines the QA strategy, test-automator executes, and code-reviewer signs off on quality and security.

QA Gate. Approval to commit and merge. The QA checklist must pass; any defect surfaced here blocks the merge.

Deployment. Cloudflare Pages auto-deploys from main on merge — no manual deployment steps. The pipeline produces the trigger; the platform handles the rest.

Deploy Gate. Confirms the change shipped as expected in production — correct behavior, no regressions, no unintended side effects.

Production. The change is live. A Post-Completion Retro captures what's worth capturing; the Learning Engine flags patterns for future pipeline improvement.

The Two-Layer Agent Architecture

The agents running this pipeline divide into two layers with a clean separation of concerns: one layer orchestrates, the other executes.

Figure 2: Two-Layer Agent Architecture — example invocations shown, not exhaustive

Figure 2: Two-Layer Agent Architecture — example invocations shown on wider screens. Layer 1 orchestrates; Layer 2 executes.

Layer 1 agents orchestrate the pipeline: they route work, apply the tier system, invoke the right specialists, and own the gate checkpoints. Layer 2 agents do the actual work — implementation, design, copy, security review, QA. The split is a deliberate architectural decision. When the pipeline itself needs to change — a new gate type, a different tier trigger — Layer 1 absorbs that change without touching the specialists. When a specialist needs to improve — a sharper code-review lens, a tighter QA strategy — that evolution happens without rewriting the pipeline. Each layer is independently iterable. That property is what lets one human run a multi-agent pipeline without the system collapsing every time something improves.

Tiers and Gate Ownership

Not every change carries the same risk — the tier system matches gate depth to the stakes of each change, so routine work moves fast and high-risk work moves carefully.

Trivial: Copy fixes, config changes, image swaps. Inline approval — no checklists required.
Standard: New pages, bug fixes, styling overhauls, minor features. Full spec, inline architecture review, required QA checklist, inline deployment confirmation.
Complex: New integrations, framework migrations, significant refactors. All checklists required; spec surfaces mandatory escalation triggers explicitly.
Critical: Authentication, payments, PII handling, core data model changes. All checklists enhanced; external second reviewer required in addition to AI-agent-structured review.

Rob owns every gate — Spec Gate, Arch Gate, QA Gate, Deploy Gate — with AI-agent-structured review at each. Critical-tier work is the one exception: it requires an external second reviewer before the gate can close. The tier system is what makes one-human-in-the-loop viable: by right-sizing gate depth to actual risk, it keeps cognitive load proportional to stakes rather than constant across every change.

The tier-and-gate-ownership model is an extension to GeekByte's foundational SDD pipeline. It was developed to make the methodology run sustainably with a single human operator, and that constraint shaped both the tier definitions and the gate structure.

Experimental Mechanisms

Four additions sit on top of the core pipeline — mechanisms for preserving the why behind decisions, not just the what.

Decision Rationale: Standard+ specs include a section capturing alternatives considered, constraints, and trade-offs — not for documentation's sake, but because future-Rob and future-agents need the why, not just the what. A decision without its rationale is a landmine for the next change that touches the same surface.
Gate Annotations: When approving a gate, the gate owner notes why — especially when overriding a recommendation. This prevents the most common failure mode in technical review processes: approvals that carry no context and can't be audited six months later.
Post-Completion Retros: After production deployment, 2–3 minutes of structured reflection. The trigger is selective — skip if nothing stood out — which means the retros that do get written are worth reading.
Stack Quirks: Platform and tool gotchas accumulated through experience, in governance/stack-quirks.md. One-liners per entry, not exhaustive documentation — close enough to the moment of discovery to be accurate, short enough to actually get written.

All four mechanisms are experimental — CLAUDE.md marks them explicitly: "Evaluate after 10 specs."

For worked examples of each mechanism above, browse the specs/ directory in the repo.

What's Working, What's Experimental, What's Evolving

This is the engineering-judgment section: an honest accounting of what's stable, what's being evaluated, and what's next.

                        
                        Working Today
                        Two-layer agent architecture — The orchestration/specialist split has been the most stable design decision in the pipeline. Across 16 shipped specs, no spec required restructuring either layer.
Tier system and escalation triggers — The four-tier system consistently produces the right gate depth without manual judgment at every spec. The tier-selection table is both the policy and the audit trail.
Spec-as-source-of-truth — Specs survive context-window resets. An agent picking up a spec mid-pipeline gets the full decision history. This is the property that makes the pipeline actually run with one human in the loop.
Why-capture mechanisms — Decision Rationale and Gate Annotations are generating real signal early — the SPEC-015 retro caught a Pareto-dominant copy option that the architect alone would have missed.
Automated deployment — Cloudflare Pages connects the repo to production: a PR merge to main triggers a deploy with no further manual steps. The Deploy Gate verifies the outcome — not the mechanism.

                    

                        Experimental
                        Dynamic spec scope decisions — When to bundle two related changes into one spec versus shipping them separately is a judgment call the pipeline doesn't yet codify. Current heuristic: share a dependency → bundle; share only a topic → separate. Not robust enough to be a rule yet.
Learning Engine agent — The Learning Engine is defined and produced the SPEC-015 retro. What's thin is the feedback loop: the agent flags patterns, but there's no scheduled review cadence to act on them. Evaluating after 10 specs whether that loop needs more structure.
Post-Completion Retros — Retros are in the methodology but only trigger when something worth capturing actually happened. So far: two retros on 17 specs. "Skip if nothing stands out" is working as designed, but it means the sample size is small.

                    

                        Evolving
                        Solo-operator gate fatigue — One human approving every gate is a cognitive load issue. The tier system mitigates by right-sizing depth to risk. That mitigation is real. At higher velocity, it won't be enough.
Cross-spec coordination — When two specs touch overlapping assets, sequencing decisions create overhead the pipeline doesn't currently automate. SPEC-015 required a logo-naming coordination note to SPEC-012. The tier system doesn't model inter-spec dependencies — that's a gap.
Memory hygiene — The Claude Code memory system requires periodic review. One record stayed stale for roughly a week after Cloudflare Pages went live before being caught at a Spec Gate. Catching it required actively reading memory, not automated expiry.
PM-Spec to Architect-Review hand-off — First-draft specs occasionally arrive with open questions that need iteration before review can proceed. This isn't a failure mode — it's expected in any spec-driven system. The friction is recognizing the pattern early enough to budget for iteration.
Spec-Gate question backlogs — First-draft specs routinely surface more open questions than they resolve (SPEC-015: 8; SPEC-016: 12). A spec that surfaces 12 questions is doing its job — resolving them at Spec Gate is the correct moment. But the walkthrough is now a time-budgeted activity, not a quick approval step.

                    

Future Evolution

Phase 1 of robcparker.com is a static marketing site. Phase 2 is an AI agent modeled on Rob's life experience. The SDD pipeline that built Phase 1 will need to evolve for that transition — new specialists (backend-developer, ai-integrations), new tier triggers (auth, AI safety review), new gates. The pipeline is designed to absorb that evolution. Tiers escalate when the trigger checklist demands it. New agents are added by writing new role files in the same shape as the existing ones. The two-layer architecture doesn't change — the inventory inside each layer does.

That property — load-bearing skeleton, replaceable parts — is not specific to this site. It's the same property that makes an engineering organization resilient through growth: a stable operating model that can absorb new tooling, new platforms, and new team members without rewiring from scratch. The methodology here is one instance of that pattern; the pattern generalizes.

Every spec, every gate decision, and every deployed change that produced this site is in the public repository — the full record is checkable.