RoRo Studio — Spec-Driven Development (SDD) Specification

How RoRo Studio adopts Spec-Driven Development for all product and client work, adapted for headless claude -p agent dispatch via Linear.

Status: v1.4 FINAL — All decisions finalized. Zero TODOs. All internal references verified. Applies to: All product development and client delivery work (Dev team) Does not apply to: Infrastructure/ops tasks (Ops team) — these use a simplified workflow without SDD phases

1. Core Principle

The specification has replaced the codebase as the primary artifact. When AI agents write code, the human’s job shifts from writing implementations to writing contracts that constrain and direct autonomous execution.

Shape -> Architect -> Specify -> Execute -> Verify -> Ship

Three immutable constraints:

Agents are stateless — every task must carry its complete context
Agents are confidently wrong ~20% of the time — compounds to near-certain failure over 20-decision features without planning and verification
Agents are fast but not wise — they optimize locally for “code that runs” rather than globally for “code that’s correct, secure, and maintainable”

2. The What/How Split

SDD artifacts are split across two systems based on content type:

Layer	System	Contains	Created by	Consumed by
The What	Linear issues	Business requirements, user stories, acceptance criteria, success metrics	Robert + agents (collaborative)	Both Robert and agents
The How	Product Git repo (`.specify/` directory)	Constitution, technical specs, implementation plans, task breakdowns	Robert + agents (collaborative)	Primarily agents
Templates	Knowledge base (`RoRoStudio/knowledge-base`)	Reusable SDD templates, constitution templates, ADR templates	Robert	Both Robert and agents

Agent-first principle

Linear issues are a collaboration artifact, not a human-only planning tool. In practice:

Agents create issues (e.g., decomposing tasks.md into Linear issues, creating sub-issues)
Agents read issues (dispatched from them via claude -p)
Agents update issues (status changes, progress comments)
Robert specifies the intent and reviews the output

When there is friction between human-optimal and agent-optimal formatting, optimize for agents. Agents execute from these issues hundreds of times; Robert reviews them once. This means:

Issue templates must have consistent, structured sections with predictable headings (not free-form prose)
Content must be machine-parseable so agents can reliably fill templates and reliably extract context from them
Every issue must carry enough context for a stateless agent to pick it up and execute without asking questions

3. Linear Workspace Configuration

3.1 Two teams

Team	Identifier	Purpose	Workflow
Dev	`DEV`	All SDD work — own products and client delivery	Agent-dispatch workflow (10 statuses)
Ops	`OPS`	Infrastructure, tooling, CI/CD, admin, and any non-SDD task	Unified dispatch workflow (10 statuses)

Why two, not one: Both teams share the same dispatch gate (“Ready” status) and workflow shape. Two teams cost minimal overhead — Robert sees both in cross-team views — while buying per-team workflow customization, separate Agent Guidance, and instant identifier-based scanning (DEV-42 = SDD work, OPS-15 = operational).

Why not three or four: Product vs. client distinction belongs at the project level (via project labels), not the team level. Separating them would duplicate workflow configuration and fracture the dispatch queue.

3.2 Workflow statuses

Dev team (10 statuses):

Category	Status	Description	Who acts
Triage	Triage	Incoming issue, unprocessed	Triage Intelligence
Backlog	Backlog	Acknowledged, not yet planned	Robert
Unstarted	Todo	Planned, being specified	Robert
Unstarted	Ready	Fully specified — dispatch gate	Agent or Robert
Started	In Progress	Work underway	Agent or Robert
Started	In Review	PR open, awaiting human review	Robert
Completed	Done	Merged and verified	—
Canceled	Canceled	Circumstances changed, replaced by other work	—
Canceled	Won’t Do	Deliberately scoped out or abandoned	—
Canceled	Duplicate	Covered by another issue (auto-set by “Mark as duplicate”)	—

The Ready status is the agent dispatch gate: the Dispatch Queue view filters for Status = Ready. Moving an issue from Todo to Ready is Robert’s explicit act of declaring “this issue is self-contained and ready for execution.” A status (not a label) because it’s mutually exclusive — an issue cannot be simultaneously Ready and In Progress.

Ops team (10 statuses):

Category	Status
Triage	Triage
Backlog	Backlog
Unstarted	Todo
Unstarted	Ready
Started	In Progress
Started	In Review
Completed	Done
Canceled	Canceled
Canceled	Won’t Do
Canceled	Duplicate

Both teams share the same workflow shape and dispatch gate. Ops issues use Ready the same way Dev issues do — Robert marks an issue Ready when it’s fully specified and ready for agent execution. For truly reactive work (incidents, urgent fixes), create the issue directly in In Progress and skip Ready. In Review is kept for infrastructure PRs.

GitHub integration auto-transitions (Dev team):

PR event	Status transition
On draft PR open	No action (agent still working)
On PR open	→ In Review
On PR review request or activity	No action (avoids premature status change during fix cycles)
On PR ready for merge	No action (manual review decides merge)
On PR merge	→ Done

Auto-close settings:

Parent auto-complete: Enabled (all sub-issues Done → parent Done)
Auto-archive completed: 30 days (Dev), 14 days (Ops)
Auto-archive canceled: 7 days (both)
Auto-close stale issues: Disabled (SDD issues in Backlog may be intentionally dormant)

3.3 Initiatives, projects, and milestones

Initiatives: use sparingly. Only when multiple projects converge toward a shared, finite strategic goal with a target date (e.g., “Launch ProductX” spanning core build + marketing site + docs). Most solo-founder work won’t need them. Start without — create one only when you mentally group 3+ projects under a shared deadline.

Projects: one per deliverable. Each product version or client engagement gets its own project in the Dev team. Ops gets projects for larger infrastructure efforts.

Project statuses (workspace-wide):

Category	Status	Use
Backlog	Concept	Early idea, not committed
Planned	Scoped	Committed, requirements being gathered
Started	In Progress	Active development
Completed	Shipped	Delivered to production or client
Canceled	Dropped	Abandoned

Project labels (workspace-level, applied to projects not issues):

Category — single-select group classifying project origin:

Label	Description
`Product`	RoRo Studio’s own products
`Client`	Paid client delivery
`Internal`	Infrastructure, tooling, operational

Project label groups are mutually exclusive — a project can only have one Category label. Create this group in Settings > Projects > Labels using the Category/Product syntax. The Category group appears as a dedicated column in project list views and is a supported slice dimension in Insights.

Milestones: the mechanism for SDD phases. Each SDD project gets 5 milestones. Milestones coexist (you can see P0 at 100%, P3 at 40% simultaneously), show completion percentages, appear on timelines, and can have target dates — superior to project statuses (single-state) or labels (no progress tracking).

Milestone	Typical duration
P0 — Shape & Validate	1–2 weeks
P1 — Architect & Contract	3–5 days
P2 — Specify & Decompose	2–5 days
P3 — Execute & Verify	2–6 weeks
P4 — Harden & Ship	3–7 days

Milestone descriptions (set in the SDD Project template):

Each milestone carries a brief description with its gate question and phase orientation. These are reference text — actual tracking happens through issues within the milestone.

P0 — Shape & Validate: Gate: “Is this worth building?” / “Is the scope clear enough to architect?” Define the problem, set appetite, sketch the solution, identify risks and no-gos. For products, validate with a prototype or landing page. For clients, validate with scope sign-off. This phase ends when you have conviction the project is worth committing to and the scope is bounded enough to make architectural decisions.
P1 — Architect & Contract: Gate: “Day 1 Readiness” — an agent can pick up the first P3 issue without asking questions. Make all major architectural decisions, define API contracts, set up project scaffolding, and build one reference vertical slice. Write the project constitution and agent context files. Every technical question an agent might ask during execution should have an answer in the repo by the end of this phase.
P2 — Specify & Decompose: Gate: All issues reviewed, acceptance criteria testable, dependency graph allows parallelism. Translate features into agent-ready specifications. Each feature gets a spec, plan, and task breakdown. Tasks must be small enough for a single agent context window (1–3 hours, ≤10 files). Sync task breakdowns to Linear. This phase ends when the Dispatch Queue has a backlog of Ready issues.
P3 — Execute & Verify: Gate: All features implemented, CI green on staging, core user journeys tested. Agents implement features from the Dispatch Queue. Robert reviews every PR. This is the longest phase — expect 2–6 weeks depending on scope. The milestone’s completion percentage tracks progress automatically as sub-issues reach Done.
P4 — Harden & Ship: Gate: Production deployed, monitoring confirms stability, success metrics are being tracked. Integration testing, security review, performance validation, and production infrastructure setup. Budget more time than you think — hardening consistently takes longer than expected. This phase ends with staging merged to main and the project marked Shipped.

3.4 Cycles

Dev team: 1-week cycles, starting Monday. Cycles don’t map to SDD phases — they map to Robert’s weekly work rhythm. A cycle forces a 15-minute Monday planning ritual: “What am I dispatching this week? What needs review?” Velocity data feeds future estimation.

Settings: Duration 1 week, upcoming cycles 4, no cooldown. Auto-add: Started=YES (captures work when execution begins), Completed=YES (prevents velocity underreporting for quick fixes), Active=NO (would pull all Ready issues into cycle, inflating scope).

Ops team: no cycles. Ops work is reactive and continuous. Cycles would create rollover noise.

Cycles vs milestones are orthogonal. Milestones track project phase progress (P3 at 40%). Cycles track weekly throughput (12 issues completed this week). An issue belongs to both simultaneously.

3.5 Labels

Issue label groups (workspace-level, single-select per group):

Execution — how the issue should be worked:

Label	Description
`Autonomous`	Agent handles end-to-end; human reviews output only
`Assisted`	Agent does implementation; human provides guidance during execution
`Manual`	Human-only work; no agent dispatch

Type — what kind of work:

Label	Description
`Feature`	New functionality or capability
`Bug`	Defect in existing behavior
`Chore`	Refactoring, dependency updates, tech debt
`Spike`	Research, exploration, proof of concept

Standalone labels (workspace-level):

Label	Description
`High Risk`	Requires extra review scrutiny; touches critical paths, auth, payments, data
`Blocked`	Waiting on external dependency; pair with a blocking issue relation

Why not four groups (Risk, Execution, Agent, Source): The Agent group duplicates workflow statuses (Ready = dispatch gate, In Review = needs review). The Source group duplicates Linear’s built-in creator field. Three risk levels collapse to a single High Risk flag — the only actionable distinction for a solo founder. Total: 8 issue labels + 3 project labels (1 group: Category).

3.6 Custom views

#	View	Filter	Group by	Sort	Purpose
1	Dispatch Queue ⭐	Status=Ready, Execution IN (Autonomous, Assisted)	Project	Priority desc, Created asc	Find next task to dispatch — both Dev and Ops. Pin as sidebar default.
2	Review Queue	Status=In Review	Project	Updated asc	Work awaiting Robert’s review. Oldest first.
3	Active Work	Assignee=me, Status category=Started	Project	Priority desc	Everything Robert is currently doing.
4	Portfolio	Project status IN (Planned, Started)	Project label (Category)	Target date asc	Bird’s-eye status of all projects. Shows milestone completion bars.
5	Stale Issues	Status category=Started, Updated date is before 5 days ago	Team	Updated asc	Surface stuck work — issues not touched in 5+ days.
6	Phase Board	Project={current}	Milestone	Priority desc	Per-project board with columns per SDD phase. Attached to each project.

3.7 Triage rules and automation

Triage rules (deterministic, instant):

#	Name	Condition	Action
1	Escalate urgent issues	Priority = Urgent	Assign to Robert
2	Escalate high-priority bugs	Label = Bug AND Priority >= High	Assign to Robert

Rule 2 originally included “add to current cycle” but this is not available as a triage rule action in Linear. Rule 3 (“keep in Triage if no project assigned”) was removed — Linear already keeps issues in Triage until manually moved, which is the desired default behavior.

Triage Intelligence (Dev team):

Property	Setting	Rationale
Assignee	Show	Suggestions help; auto-apply would be wrong for solo+agents
Project	Show	Project assignment requires human judgment
Label	Auto-apply	Type labels (Feature/Bug/Chore/Spike) are safe to auto-classify
Team	Show	Helps surface issues that should route to Ops
Duplicate issue	Show	Surface potential duplicates for human decision
Related issue	Show	Useful context for connected work

Triage Intelligence guidance text (Dev team):

Issues referencing .specify/ files or OpenAPI contracts are always Type: Feature.
Issues mentioning CI, pipeline, Docker, or deployment should be routed to the Ops team.

Personal git automations (Robert’s account preferences):

On git branch copy, move issue to started status = Enabled
On move to started status, assign to yourself = Enabled
On open in coding tool, move to started status = Disabled (reading context is not starting work)
Auto-assign to self on issue creation = Disabled (issues are created for agents too)

3.8 Agent Guidance

Decision: do not duplicate instructions in Linear Agent Guidance. All agent instructions live in AGENTS.md in each project repository. CLAUDE.md imports AGENTS.md via @AGENTS.md and adds Claude-specific extensions. This keeps a single source of truth in the repo, avoids maintenance drift between Linear and Git, and works for all dispatch mechanisms (claude -p, Claude Code Desktop, future agents).

Linear Agent Guidance (Settings > Agents > Additional guidance) is left empty at both workspace and team level. Linear’s own docs note: “All guidance is passed to the agent, but how it is interpreted or applied depends on the specific agent integration.” Since RoRo Studio dispatches agents via claude -p (which reads AGENTS.md/CLAUDE.md from the repo, not Linear), duplicating instructions in Linear would create a second source of truth with no enforcement mechanism.

If a future Linear-native agent integration (e.g., @mention-based dispatch) requires guidance, add a minimal pointer: “All instructions are in AGENTS.md in the project repository.”

3.9 Parent/sub-issue patterns

P3: features as parents, tasks as sub-issues. The sync script creates a parent issue per feature (Feature: User Authentication) and individual tasks as sub-issues. As agents complete sub-issues, the parent’s progress bar fills. When all sub-issues reach Done, the parent auto-completes. Only sub-issues are dispatched to agents — parents have Execution = Manual so the Dispatch Queue excludes them automatically.

Other phases: flat issues, no sub-issues. P0–P2 issues are standalone specification or research tasks. P4 issues may optionally use sub-issues when a hardening effort has multiple verification tasks.

3.10 Naming conventions

Entity	Convention	Example
Project	`{ProductName} v{X.Y}` or `{ClientName} — {Scope}`	`Launcher v1.0`, `Acme — Dashboard`
Milestone	`P{N} — {Phase Name}`	`P0 — Shape & Validate`
Feature (parent)	`Feature: {Name}`	`Feature: User Authentication`
Task (sub-issue)	`T{N} — {Description}`	`T1 — Implement login endpoint`
Spec issue	`Spec: {Name}`	`Spec: API Architecture`
Bug	Plain descriptive title	`Login fails on expired session token`
Ops task	Plain descriptive title	`Upgrade Node.js to v22 LTS`
Git branch	`{issue-id}-{slug}`	`dev-42-implement-login-endpoint`
Commit	`type(scope): description [DEV-{N}]`	`feat(auth): add login endpoint [DEV-42]`

All conventions use — (em dash with spaces) as separator for visual consistency.

4. Repository Structure — Language-Agnostic Monorepo

Every product/client deliverable is a monorepo with a universal structure that is completely language-agnostic at the foundational level. Language-specific aspects (build commands, test runners, package manifests, internal directory conventions) are pluggable extensions within per-project directories — never embedded in the foundation.

Build orchestrator: Moon + Just (standard for all projects). Moon provides native polyglot toolchain management, cross-language dependency resolution, and affected-only CI runs. Just provides human-friendly convenience commands that delegate to Moon.

Universal directory structure

product-repo/
|-- .specify/                      # SDD artifacts (language-agnostic)
|   |-- constitution.md            # Project-level governing principles
|   |-- specs/
|   |   |-- 001-feature-name/
|   |   |   |-- spec.md            # Requirements + acceptance criteria
|   |   |   |-- plan.md            # Technical design + decomposition rationale
|   |   |   `-- tasks.md           # Source of truth for task breakdown
|   |   `-- 002-another-feature/
|   |       |-- spec.md
|   |       |-- plan.md
|   |       `-- tasks.md
|   `-- templates/                 # Project-local template overrides (optional)
|-- apps/                          # Deployable frontends (web, mobile, CLIs)
|-- services/                      # Backend services (APIs, workers, processors)
|-- packages/                      # Shared libraries (never deployed alone)
|-- contracts/                     # Cross-language API contracts (OpenAPI, protobuf)
|   |-- openapi/                   # REST API specs (source of truth)
|   |-- proto/                     # Protobuf schemas (if applicable)
|   `-- gen/                       # Generated client code (DO NOT EDIT)
|-- docs/
|   |-- architecture.md            # C4 diagrams, data model, module boundaries
|   `-- decisions/                 # Architecture Decision Records
|       |-- ADR-001-tech-stack.md
|       `-- ADR-002-api-style.md
|-- scripts/                       # Repo-wide automation
|   |-- verify.sh                  # Universal verification ladder
|   |-- generate-clients.sh        # Regenerate contract code
|   `-- roro-sync                  # tasks.md -> Linear sync script
|-- infra/                         # Infrastructure-as-code (when needed)
|-- tooling/
|   `-- templates/                 # Scaffolding templates per language
|-- .github/
|   |-- workflows/
|   |   |-- ci.yml                 # Path-based change detection -> per-language pipelines
|   |   `-- reusable-{language}.yml # One reusable workflow per language
|   `-- pull_request_template.md
|-- .claude/
|   `-- rules/                     # Language-specific rules (loaded on demand by path glob)
|-- .moon/
|   |-- workspace.yml              # Project discovery
|   |-- toolchains.yml             # Pinned language versions
|   `-- tasks/                     # Per-language task definitions (build/test/lint)
|-- AGENTS.md                      # Cross-tool agent orientation (~80 lines)
|-- CLAUDE.md                      # Imports @AGENTS.md + Claude-specific extensions
|-- CONVENTIONS.md                 # Cross-language naming and style conventions
|-- CODEMAP.md                     # Domain-concept-to-path mapping (multi-service projects)
|-- CODEMAP.yaml                   # Machine-readable variant
|-- README.md                      # Human-oriented project overview
|-- justfile                       # Human-friendly commands delegating to Moon
|-- .editorconfig                  # Universal editor settings
|-- .gitattributes                 # Generated file markers
`-- CODEOWNERS                     # Ownership mapping

Directory semantics

Directory	Contains	Deployment	Rule
`apps/`	User-facing frontends	Deployed independently	If it faces users, it’s an app
`services/`	Backend APIs, workers	Deployed independently	If it faces apps, it’s a service
`packages/`	Shared libraries	Never deployed alone	If it’s consumed via import, it’s a package
`contracts/`	API definitions (OpenAPI, protobuf)	Never deployed	Source of truth for cross-language types
`.specify/`	SDD artifacts	Never deployed	Source of truth for specifications

VSA within each deployable unit

The top-level split (apps/services/packages) is by deployment topology. Within each app or service, code follows Vertical Slice Architecture — grouped by domain feature, not technical layer. The internal structure follows each language’s idioms:

Go: internal/{domain}/handler.go + service.go + repository.go + model.go (compiler-enforced privacy via internal/)
Python: src/{package}/{domain}/router.py + service.py + schemas.py (src/ layout, PEP 517)
TypeScript: src/features/{domain}/ or framework conventions (Next.js App Router route groups)
Rust: src/{domain}/mod.rs + ...

Each app/service carries its own AGENTS.md with language-specific commands, loaded on demand when the agent works in that directory (progressive disclosure).

What to add when

Not every file needs to exist from day one:

Timing	Add
Day 1	AGENTS.md, CLAUDE.md, .specify/, justfile, .editorconfig, .github/ci.yml, scripts/verify.sh, .moon/ config, one app or service, CODEOWNERS, .env.example
Phase 1 (Architect)	docs/architecture.md, docs/decisions/, CONVENTIONS.md, contracts/ (if multi-language)
First cross-language boundary	CODEMAP.md, generate-clients.sh, contract validation in CI
After 3 observed agent mistakes	.claude/rules/ entries (reactive, not prophylactic)
Production deployment	infra/, deployment scripts, runbooks

Constitution.md

The constitution is the project’s supreme guiding document — non-negotiable principles referenced at spec-writing time (Phase 2).

Constitution = “what” principles: Core technology principles, quality standards, security requirements, naming conventions, explicit out-of-scope items.

CLAUDE.md = “how” operations: Build/test/lint commands, file path conventions, tool-specific instructions, boundary rules.

No overlap. Constitution says “all APIs must validate input” (principle). CLAUDE.md says “use zod for validation, see services/api/internal/auth/ for the pattern” (operational).

Spec documents (per feature)

Document	Phase	Purpose	Author
`spec.md`	Phase 2	Requirements: user stories, Given-When-Then acceptance criteria using RFC 2119 keywords	Robert (human)
`plan.md`	Phase 2	Technical design: component architecture, data model, error handling, task decomposition rationale	Robert + agent
`tasks.md`	Phase 2	Source of truth for task breakdown: discrete work items with metadata, synced one-way to Linear	Robert + agent

tasks.md format

# Feature: User Authentication
 
## P3 Tasks
 
- [ ] T1 — Implement login endpoint <!-- DEV:Autonomous:High -->
  Spec: .specify/specs/user-auth/spec.md
  Depends: none
 
- [ ] T2 — Add session middleware <!-- DEV:Autonomous:High -->
  Spec: .specify/specs/user-auth/spec.md
  Depends: T1
 
- [ ] T3 — Build auth UI components <!-- DEV-48:Assisted:Medium -->
  Spec: .specify/specs/user-auth/spec.md
  Depends: T1

HTML comments encode metadata: . Before first sync, no Linear ID. After sync, the script writes back the assigned ID.

5. Phase-by-Phase Workflow

Phase 0 — Shape & Validate (Human only, 1–2 weeks)

Objective: Define what to build, validate it’s worth building.

For products — full process: Shape Up pitch (problem, appetite, solution sketch, rabbit holes, no-gos), cheap validation (prototype, landing page, concierge MVP), 2–3 hypotheses with success metrics, Lean Canvas.

For client work — adapted pitch, no Lean Canvas: Problem framing, appetite (budget → time), solution sketch, rabbit holes, no-gos (scope boundaries), success metrics.

Linear: Create project using SDD Project template (pre-fills pitch in description, creates P0–P4 milestones). Set project label (Product or Client). Create P0 issues (e.g., “Build prototype”, “Client scope review”). Status: Todo → Done.

Gate: “Is this worth building?” / “Is the scope clear enough to architect?”

Phase 1 — Architect & Contract (Human + single agent, 3–5 days)

Objective: Make all architectural decisions, define contracts, set up scaffolding.

Activities: Write ADRs, design database schema (~70%), write OpenAPI 3.1 contracts, set up project scaffolding, write CLAUDE.md + AGENTS.md + architecture.md, create constitution.md, build one reference vertical slice.

Linear: Architecture tasks in P1 milestone. Mostly Manual or Assisted execution. Status: Todo → Ready → In Progress → Done.

Gate: “Day 1 Readiness” — an agent can pick up the first P3 ticket without asking questions.

Phase 2 — Specify & Decompose (Human, 2–5 days per cycle)

Objective: Translate features into agent-ready specifications.

Activities: Create .specify/specs/NNN-feature/ with spec.md, plan.md, tasks.md per feature. Run sync script to create Linear issues from tasks.md.

Task granularity: 1–3 hours AI work, ≤10 files, ≤500 lines, one verifiable outcome, fully self-contained.

Linear: Spec-writing tasks (Spec Issue template) in P2 milestone. Sync script creates Feature parents and task sub-issues in P3 milestone. Status: Todo → Done.

Gate: Tickets reviewed, acceptance criteria testable, dependency graph allows parallelism.

Phase 3 — Execute & Verify (Agents + human reviewer, 2–6 weeks)

Objective: Agents implement features; Robert reviews every PR.

Git branching: Agents branch from staging, merge to staging sequentially, rebase remaining. Staging → main after Phase 4.

PEV loop per ticket: Plan (agent reads spec) → Execute (agent implements) → Verify (agent runs verification commands). Then Robert reviews the PR.

Dispatch command pattern:

claude -p "Implement DEV-42: T1 — Implement token validation.
 
Issue context: [paste issue description from Linear]
 
Read the specification at .specify/specs/user-auth/spec.md before starting.
Follow CLAUDE.md conventions. Branch from staging.
Run all verification commands before creating PR." \
  --allowedTools "Read,Edit,Bash" \
  --output-format json

Modified ATDD: Robert writes specs → agent generates tests → Robert reviews tests (non-negotiable) → agent implements until tests pass → CI quality gates → Robert reviews PR.

Linear: Implementation issues in P3 milestone. Dispatch via Dispatch Queue view. GitHub auto-transitions handle status. Parent issues auto-complete when all sub-issues Done.

Gate: All features implemented, CI green, staging works, core journeys tested.

Phase 4 — Integrate, Harden & Ship (Human + agents, 3–7 days)

Objective: Integration testing, security hardening, production readiness.

Activities: Full integration tests, manual security review, performance testing, production setup, monitoring, feature flags. Budget 2–3× Phase 3 effort.

Linear: Hardening tasks (Hardening Issue template) in P4 milestone. Merge staging → main. Project status → Shipped.

Gate: Production deployed, monitoring stable, success metrics tracked.

6. Agent Context System

CLAUDE.md — Loaded automatically (<80 lines)

# Project: [Name]
 
## Commands
- Build: `[command]`
- Test: `[command]`
- Lint: `[command]`
- Type check: `[command]`
 
## Architecture
- See docs/architecture.md for system design
- Before modifying auth, read docs/decisions/ADR-NNN.md
 
## Conventions
- [Only rules that differ from defaults]
 
## Boundaries
NEVER: modify migration files after they've been applied
NEVER: add dependencies without approval
NEVER: disable strict mode or linting rules
NEVER: handle, generate, or transport credentials
ASK FIRST: changes to shared types or database schema
ASK FIRST: new environment variables
ALWAYS: write tests for new features
ALWAYS: use existing patterns from the reference vertical slice as templates
ALWAYS: run verification commands before marking complete
ALWAYS: read .specify/constitution.md before starting work

AGENTS.md, architecture.md, ADRs

AGENTS.md: cross-tool canonical instructions. CLAUDE.md imports via @AGENTS.md. architecture.md: C4 diagrams (Mermaid), data model, module boundaries, error handling, deployment topology. ADRs: under 300 words each, extended Nygard format with “Implications for Agent Implementation” section.

7. Quality Assurance Strategy

CI/CD Quality Gates (GitHub Actions)

5-layer framework as standard. Exact tools per project ADR in Phase 1.

Layer	What	Time
1 — Static checks	Linting, type checking, formatting	~30s
2 — Security scanning	SAST (Semgrep), secret detection (Gitleaks), dependency audit	~2min
3 — Test execution	Unit + integration tests, coverage ≥80% on new code	~5min
4 — Pattern analysis	Architecture fitness, TODO scanning, duplication detection	~5min
5 — AI-powered review	Automated first pass (CodeRabbit or similar)	~90s

Human Review Checklist

Error handling, external API verification, security surface, existing code reuse, test quality, unrelated changes.

8. Issue Templates

Seven issue templates + one project template. All agent-first: structured sections, consistent headers, machine-parseable. Template names use “Issue” terminology (not “Task”) to match Linear’s entity model.

8.1 Agent Issue

Use: P3 autonomous execution issues. Most-used template. Pre-fills: Team=Dev, Status=Ready, Execution=Autonomous

## Context
<!-- Why this issue exists and what it builds on. -->
 
## Specification
Spec: `.specify/specs/{feature}/spec.md`
Contract: `contracts/openapi/{api}.yaml`
 
## Acceptance criteria
- GIVEN {precondition} WHEN {action} THEN {result} -- MUST
- GIVEN {edge case} WHEN {action} THEN {behavior} -- MUST
 
## Scope boundaries
- MUST NOT modify files outside: {list}
 
## Files
- `src/{path}/file` -- {what to do}
- `src/{path}/file.test` -- {what to test}

8.2 Assisted Issue

Use: Issues requiring both agent and human work. Separated sections so Robert always sees who does what. Pre-fills: Team=Dev, Status=Todo, Execution=Assisted

## Context
<!-- Why this issue exists. -->
 
## Specification
Spec: `.specify/specs/{feature}/spec.md`
 
## Agent tasks
1. {specific implementation step}
2. {specific implementation step}
 
## Manual tasks (Robert)
1. {specific manual action}
2. {specific manual action}
 
## Execution order
1. Robert: {manual step -- must complete before agent starts}
2. Agent: {implementation steps}
3. Robert: {manual step -- depends on agent output}
 
## Acceptance criteria
- GIVEN {precondition} WHEN {action} THEN {result} -- MUST
 
## Scope boundaries
- MUST NOT modify files outside: {list}

8.3 Manual Issue

Use: Human-only Dev work that is not specification writing or hardening (e.g., setting up external service accounts, architecture reviews, manual deployment steps). Pre-fills: Team=Dev, Status=Todo, Execution=Manual

## Objective
<!-- What needs to be done and why. -->
 
## Done when
- [ ] {completion criterion}

8.4 Spec Issue

Use: P1—P2 specification work. Pre-fills: Team=Dev, Status=Todo, Execution=Manual

## Objective
<!-- What specification artifact to produce. -->
 
## Deliverables
- [ ] Spec file: `.specify/specs/{feature}/spec.md`
- [ ] OpenAPI contract: `contracts/openapi/{api}.yaml`
- [ ] Task decomposition: `.specify/specs/{feature}/tasks.md`
 
## Constraints
<!-- Technical, business, or architectural constraints. -->
 
## Done when
- [ ] Spec reviewed and committed to repo
- [ ] Contract validates against OpenAPI 3.1
- [ ] tasks.md synced to Linear issues

8.5 Hardening Issue

Use: P4 quality hardening. Pre-fills: Team=Dev, Status=Todo, Execution=Assisted

## Objective
<!-- What needs hardening. -->
 
## Agent tasks
1. {hardening implementation}
2. {additional test coverage}
 
## Manual tasks (Robert)
1. {manual security review items}
2. {manual performance testing}
 
## Acceptance criteria
- GIVEN {edge case} WHEN {action} THEN {graceful handling} -- MUST
- Performance: {metric} must be under {threshold}
- Security: {checklist item}
 
## Rollback plan
<!-- Steps to reverse if it fails in production. -->

8.6 Bug Report

Use: Defect reporting. Pre-fills: Team=Dev, Status=Triage, Type=Bug

## Steps to reproduce
1.
2.
3.
 
## Expected behavior
 
## Actual behavior
<!-- Error messages, screenshots, logs. -->
 
## Environment
<!-- OS, browser, API version, commit SHA. -->
 
## Severity
<!-- blocking / degraded / cosmetic -->

8.7 Ops Issue

Use: Non-SDD operational work. Pre-fills: Team=Ops, Status=Todo

## Task
<!-- What needs to be done. -->
 
## Context
<!-- Why this is needed now. -->
 
## Done when
- [ ] {completion criterion}

SDD Project Template

Pre-configured: Status=Scoped, five milestones (P0—P4) with gate questions and phase orientation in each milestone description (see Section 3.3).

Description (products — full Shape Up pitch):

## Problem
<!-- Who has this problem? Why does it hurt? -->
 
## Appetite
<!-- Time budget -- ceiling, not estimate. -->
 
## Solution sketch
<!-- Breadboard-level flow. Key interactions. -->
 
## Rabbit holes
<!-- Known risks. Things that could derail the build. -->
 
## No-gos
<!-- What we will NOT build. Explicit scope boundaries. -->
 
## Success criteria
<!-- 2--3 hypotheses. What numbers tell us this works. -->
 
## Spec directory
`.specify/specs/`
 
## Repository
`github.com/RoRoStudio/{repo}`
 
## Key dates
- Target ship: {date}

For client projects: replace Problem/Appetite/Rabbit holes with client brief, budget, scope boundaries. Remove hypotheses. Add “Client deadline.”

9. Tasks.md → Linear Sync Mechanism

Architecture

Direction: One-way, tasks.md → Linear. tasks.md is canon. Linear reflects it.

Status exception: Robert sees status in Linear and may update tasks.md checkboxes manually. The sync script does not write Linear statuses back.

Mechanism: Custom TypeScript script using @linear/sdk, run manually during P2 or via optional GitHub Action.

Sync script behavior

1. PARSE tasks.md → extract tasks with metadata
2. FOR each task WITHOUT a Linear ID:
   a. CREATE issue in Linear (title, team, status, labels, priority,
      project, milestone, description from Agent Issue template, parent)
   b. WRITE Linear ID back to tasks.md HTML comment
   c. COMMIT updated tasks.md
3. FOR each task WITH a Linear ID:
   a. UPDATE title if changed
   b. UPDATE status: if [x] and Linear ≠ Done → set Done
   c. UPDATE labels/priority if metadata changed
4. CREATE issue relations from Depends lines

Invocation

# Manual (primary) — during P2:
npx roro-sync --project "Launcher v1.0" --file .specify/specs/user-auth/tasks.md
 
# GitHub Action (optional, after workflow stabilizes):
# Trigger on push to .specify/**/tasks.md

Why not n8n: Simple enough for a single script. n8n adds maintenance overhead without justification.

Why not bidirectional: Eliminates conflict resolution complexity. One source of truth, one direction.

10. Anti-Patterns to Prevent

Anti-Pattern	Prevention
Shipping unreviewed code	Robert reviews every PR; no auto-merge
Security void	Security requirements in every spec; Semgrep + Gitleaks in CI
Destructive autonomy	Network isolation; read-only DB by default; RoRo Secrets air-seal
Context starvation	CLAUDE.md + architecture.md + ADRs; explicit file refs in tickets
The 70% trap	Small tasks with fresh context windows; 2–3× hardening budget
Code duplication	DRY enforcement in CLAUDE.md; refactoring passes
Architectural drift	Constitution.md as authority; contract-first development
Zombie context	One task per `claude -p` invocation; fresh context every time

11. Knowledge Base Templates

Stored in RoRoStudio/knowledge-base, indexed by RoRo Knowledge MCP:

Template	Purpose
`sdd/constitution-template.md`	Starting point for new project constitutions
`sdd/spec-template.md`	Feature specification template (spec.md)
`sdd/plan-template.md`	Technical implementation plan template (plan.md)
`sdd/tasks-template.md`	Task breakdown template with metadata format
`sdd/adr-template.md`	Architecture Decision Record (extended Nygard)
`sdd/lean-canvas-template.md`	Lean Canvas for Phase 0 (products only)
`sdd/pitch-template-product.md`	Shape Up pitch for products
`sdd/pitch-template-client.md`	Adapted pitch for client work

12. Resolved Decisions

Methodology decisions

Decision	Resolution
Scope	Product + client work via Dev team; infra/ops via Ops team
Spec location	What (Linear) / How (Git `.specify/`) split
Spec Kit adoption	Custom RoRo approach, no CLI dependency
Contract-first	OpenAPI 3.1 for all APIs (mandatory)
Phase 0 depth	Tiered (full for products, adapted for clients)
VSA	Adopted for all repos: monorepo with apps/services/packages, VSA within each unit
Build orchestrator	Moon + Just as standard for all projects
Repo pattern	Monorepo per product/client deliverable as default
Git branching	`main` + `staging` with feature branches from `staging`
Tasks.md	Source of truth, one-way sync to Linear with ID writeback
Constitution vs CLAUDE.md	Constitution = principles, CLAUDE.md = operations
CI/CD quality gates	5-layer framework, tools per project ADR
Ticket spec format	Given-When-Then, RFC 2119, boundaries, verification commands

Linear configuration decisions

Decision	Resolution
Teams	Dev (SDD, 10 statuses) + Ops (non-SDD, 10 statuses)
Dispatch gate	”Ready” workflow status on both teams (not a label)
Initiatives	Sparingly — only for multi-project goals with target dates
Projects	One per deliverable + project label group (Category: Product/Client/Internal)
Milestones	SDD phases P0–P4 per project
Cycles	Dev: 1-week Monday. Ops: none
Labels	2 groups (Execution, Type) + 2 standalone (High Risk, Blocked)
Templates	7 issue + 1 project (Agent, Assisted, Manual, Spec, Hardening, Bug Report, Ops)
Views	Dispatch Queue, Review Queue, Active Work, Portfolio, Stale, Phase Board
Naming	Feature:, T{N}, Spec:, P{N}, em-dash separators
Parent/sub-issues	P3: Feature parents + task sub-issues, auto-complete
Git auto-transitions	Branch→In Progress, PR→In Review, Merge→Done
Agent Guidance	Empty in Linear — all instructions centralized in AGENTS.md per repo (single source of truth)
Sync	One-way tasks.md→Linear, TypeScript script, manual invocation

This document is version 1.4 — FINAL. All methodology, Linear configuration, and repository structure decisions are finalized. Zero TODOs remain. All internal path references verified consistent. This spec is the authoritative SDD process for RoRo Studio and should be stored in the knowledge base.

RoRo Studio KB

Explorer

Spec-Driven Development (SDD) Specification