App Architect

On first invocation, read `references/orchestrator.md` and follow its welcome protocol.

Unified planning + build skill. Takes a concept from idea through spec, design, and roadmap (planning phases with user approval gates), then builds it sprint-by-sprint using a Generator → Evaluator harness (build phase with automated QA).

This is one skill, not two. Planning and building are the same pipeline.

/oc-app — Command Reference

APP ARCHITECT COMMANDS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  PLANNING PHASES
  /oc-discover       Discovery interview (Phase 1)
  /oc-spec           Spec generation + oc-stack-forge (Phase 2)
  /oc-design         Design pipeline — style book, wireframes, prototypes (Phase 3)
                    auto-routes data-heavy screens to /oc-data-forge
  /oc-roadmap        Sprint plan generation (Phase 4)

  BUILD PHASES
  /oc-scaffold       Generate runnable project structure (Phase 5)
  /oc-build          Start or resume Generator → Evaluator sprint loop (Phase 6)
  /oc-launch         Launch checklist + deploy handoff (Phase 7)

  UTILITIES
  /oc-app            Show this menu

  SESSION
  /checkpoint     Show checkpoint status
  /checkpoint show    Full checkpoint JSON
  /checkpoint reset   Archive and restart

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

The rest are plain requests, not slash commands: "export the master spec" (a .docx of the spec set), "show the punch list" (view or edit screens and components), "run the Evaluator on this sprint" (ad-hoc QA), "approve" at a gate, and "show the sprint contract" (sprints/sprint-N/contract.md).

Architecture

CONCEPT
  │
  ▼
┌─────────────────── PLANNING (user-driven, gate-controlled) ──────────┐
│                                                                      │
│  Phase 1: Discovery ──► Phase 2: Spec ──► Phase 3: Design           │
│  (interview)      ★GATE  (+ oc-stack-forge) ★GATE  (style+wireframes)  │
│                                                    ★GATE             │
│  Phase 4: Sprint Plan                                                │
│  (roadmap → sprint decomposition)  ★GATE                             │
│                                                                      │
└──────────────────────────────┬───────────────────────────────────────┘
                               │
                               ▼
┌─────────────────── BUILD (agent-driven, evaluator-controlled) ──────┐
│                                                                      │
│  Phase 5: Scaffold (one-time project setup)                          │
│                                                                      │
│  Phase 6: Sprint Build Loop (repeat per sprint)                      │
│  ┌────────────┐  contract   ┌─────────────┐                         │
│  │ GENERATOR  │◄──negotiate──►│ EVALUATOR  │                         │
│  │ builds +   │              │ grades +    │                         │
│  │ tests      │──code+tests─►│ reports     │                         │
│  │            │◄──feedback───│ (skeptical) │                         │
│  └────────────┘              └─────────────┘                         │
│       PASS → next sprint | FAIL → iterate | MAX → escalate          │
│                                                                      │
│  Phase 7: Launch                                                     │
│  (audit gate → deploy → monitor)                                     │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘

Why One Skill?

Earlier versions of opchain split planning and building into two skills with a fuzzy handoff between them. Both produced specs. Both decomposed sprints. Both tried to scaffold. Merging them into oc-app-architect eliminates:

• Duplicate spec generation
• Conflicting sprint formats
• The "which skill do I use now?" question
• Context loss at the planning → building transition

The planning phases remain user-driven with approval gates (you stay involved in every design decision). The build phases use the Generator → Evaluator loop (automated QA that catches what single-pass generation misses). Same skill, different operating modes.

Session Persistence (Checkpoint Protocol)

Checkpoint: {project-dir}/.checkpoints/oc-app-architect.checkpoint.json

Resume on Start

When any command is invoked:

1. Check for checkpoint
2. If exists: show phase, gates, sprint scores, next action
3. Ask: "Continue, restart, or show full checkpoint?"

progress_table

[
  { "id": "discovery",       "label": "Discovery interview",      "status": "not_started" },
  { "id": "spec",            "label": "Spec + oc-stack-forge",        "status": "not_started" },
  { "id": "spec-gate",       "label": "★ Spec approval",           "status": "not_started" },
  { "id": "design",          "label": "Design pipeline",           "status": "not_started" },
  { "id": "design-gate",     "label": "★ Design approval",         "status": "not_started" },
  { "id": "punch-list",      "label": "Punch list",                "status": "not_started" },
  { "id": "punch-gate",      "label": "★ Punch list approval",     "status": "not_started" },
  { "id": "sprint-plan",     "label": "Sprint plan",               "status": "not_started" },
  { "id": "sprint-gate",     "label": "★ Sprint plan approval",    "status": "not_started" },
  { "id": "scaffold",        "label": "Scaffold generation",       "status": "not_started" },
  { "id": "sprint-1",        "label": "Sprint 1: [name]",          "status": "not_started" },
  { "id": "sprint-2",        "label": "Sprint 2: [name]",          "status": "not_started" },
  { "id": "sprint-3",        "label": "Sprint 3: [name]",          "status": "not_started" },
  { "id": "launch",          "label": "Launch & deploy",           "status": "not_started" }
]

Write checkpoint after every gate approval, sprint contract, evaluation round, and sprint completion.

Phase 1: Discovery Interview (/oc-discover)

Conduct a structured interview. Group questions 2-3 per round. Skip what's already known from context.

Core Concept: Problem, pitch, prior art, existing workflow being replaced. Users & Scope: Primary users (role, context, goals, anti-goals), single/multi-user, MVP vs. full vision. Technical Context: Framework preferences, existing systems, hard constraints, offline/ real-time/data-heavy requirements. Business Context: Personal/internal/commercial, monetization, success metrics.

Summarize back to user in 3-5 sentences. Confirm before proceeding. Write checkpoint: phase "discovery", with the confirmed summary (requirements, users, constraints, budget, team experience) in context_primer.key_decisions — that is where oc-stack-forge reads the discovery context in Phase 2.

Phase 2: Spec Generation (/oc-spec)

Spec Scaffold (first step of /oc-spec)

Before any spec content, /oc-spec runs the scaffold — from the opchain plugin, node "${CLAUDE_PLUGIN_ROOT}/scripts/scaffold-spec.mjs" --root "$(git rev-parse --show-toplevel)" (the same convention /oc-enroll uses); in the opchain repo itself, node scripts/scaffold-spec.mjs. It creates spec/00…10 as stubs whose first line names the producing skill or verb, derived from the Spec Documents table below: 00-project-overview.md → /oc-discover, 01-tech-stack.md, 07-devops.md and 10-cost-estimate.md → oc-stack-forge, 06-testing.md → /oc-qa pyramid, and the rest (02–05, 08, 09, including 03-security-auth.md and 04-integrations.md) → /oc-spec itself. A stub is replaced, not appended to, when its producer runs. The producer line is what a gate would read: refusing a commit while any stub still carries its producer line, on a repository whose oc-app-architect checkpoint is in a build phase (sprint-*, launch), is specified, not yet wired. Until a hook does it, check it yourself before the first build sprint: re-running the scaffold prints the stubs still waiting for their producer (it never overwrites a written file), and a build does not start on one. The 2026-10-08 audit's one-week launch had no spec/ tree at all, so every artifact-keyed handoff in orchestrator.md §3 silently never existed; the stubs make the missing artifact visible.

Stack Selection (chains to oc-stack-forge)

Before generating spec files, hand off to oc-stack-forge per orchestrator.md §3 (Active Invocation):

1. State the chain: "Discovery is approved. Now using oc-stack-forge to choose the stack."
2. Read oc-stack-forge/SKILL.md and oc-stack-forge/references/orchestrator.md.
3. Check for .checkpoints/oc-stack-forge.checkpoint.json (resume if present).
4. Invoke the Skill tool with skill "oc-stack-forge" and args "/oc-stack-decide — <discovery context>" (platform → backend → database → auth → frontend). Stack-forge web-searches for current framework status before recommending.
5. Stack-forge returns the recommendation; if the user already stated preferences during discovery, oc-stack-forge validates the choice rather than re-interviewing.
6. Present recommendation → user confirms → stack informs all remaining spec files in this phase.

AI-App Branch (chains to the v1.5 AI-native skills)

If discovery surfaced an AI app — the product's core value depends on an LLM in the loop (chatbot, agent, RAG/search-over-docs, summarizer/extractor, copilot, eval-driven prompt product) — Phase 2 takes an extra branch after the stack decision and before writing the spec docs. Detect it from discovery signals: "Claude", "GPT", "LLM", "AI", "agent", "chatbot", "RAG", "embeddings", "semantic search", "summarize/extract/classify with a model".

Route per orchestrator.md §3 (Active Invocation), only to the skills the app actually needs:

Rules:

1. Run the AI-app branch after oc-stack-forge so the LLM/vector choices sit

on top of a chosen platform (e.g. rag-forge's vector-DB pack must be compatible with the deploy target).

1. oc-claude-api is the hub: oc-rag-forge and oc-agent-forge both pull model

routing from it rather than re-deciding. Invoke the Skill tool with skill "oc-claude-api" and args "/oc-claude-api — <AI-app discovery context>" first when more than one AI skill applies.

1. Each invoked skill writes its own checkpoint; app-architect reads them back

to assemble the AI sections of the spec. Add an 11-ai-architecture.md spec doc capturing model routing, caching strategy, retrieval design, agent topology, and the eval plan — whichever apply.

1. Not an AI app? Skip this branch entirely — no AI skill is invoked and the

spec set is unchanged.

Data-Heavy Branch (chains to oc-data-ops, v1.9)

If discovery surfaced a data-heavy backend — the product ingests, transforms, or serves datasets beyond its own operational tables (analytics warehouse, event streams, third-party data feeds, "we need dbt", reporting marts) — chain to oc-data-ops after the stack decision, same pattern as the AI-app branch:

1. Run it after oc-stack-forge (warehouse/queue choice is a stack-forge

input oc-data-ops consumes, never re-decides).

1. Invoke the Skill tool with skill "oc-data-ops" and args "/oc-data-ops design — <discovery context>"; its layer map +

data contracts fold into 02-architecture.md (data model section) and the contract rows feed oc-qa-ops' matrix in 06-testing.md.

1. Detect it from discovery signals: "pipeline", "warehouse", "dbt", "ETL/ELT",

"events", "reporting", "data feed", "sync data from X". An app whose only data is its own CRUD tables does not take this branch.

Spec Documents

Generate each as a separate markdown file:

Source "spec-template" and "architecture-patterns.md" mean: read references/spec-template.md (section headings per doc) and references/architecture-patterns.md before writing that doc.

★ Spec Approval Gate

User reviews: data model, API contract, security model, scope. Do not proceed until explicitly approved. Write checkpoint: phase "spec-approved".

Phase 3: Design Pipeline (/oc-design)

Read references/ux-design-guide.md for the full methodology.

Navigation rule — top navigation only (hard rule, added 2026-10-07). Primary navigation on every surface — public sites, apps, admin and CRM shells, dashboards, docs — is a top bar / header. On phones the header keeps a menu button (or a bottom tab bar); the menu it opens is part of the top nav. A left or right sidebar or rail used as primary navigation is a regression and a blocking FAIL, no matter what the design direction, template, component library, reference app or prior version shows. Not covered (allowed): an in-page table of contents, filter panels, a record's detail side panel, a settings sub-menu inside a page. The only exception is the project owner's written approval for one named screen, recorded in the checkpoint's skill_state.nav_exceptions[] ({screen, date, quote}); it never carries over to another screen or a later redesign. An existing sidebar found in a project is a migration item on the punch list, not a pattern to copy. It binds every Phase 3 artifact (style book, wireframes, prototypes, punch list), the oc-dash-forge handoff, the oc-ux-engineer Design Evaluator and the Phase 6 Evaluator.

3a. Style Book

Interactive HTML showing all design tokens live: colors, typography, spacing, borders, component examples (buttons, forms, cards in all variants × states).

Token discipline:

• Colors must be semantic, not aesthetic. Every color has a role: chrome / state / accent / series. Do not ship a palette of 12 brand hues without role assignment.
• Type ramp ≤ 5 steps. Display / headline / body / caption / micro. More sizes = more cognitive tax.
• Spacing on a scale. 4/8/12/16/24/32/48/64 — not arbitrary px values per component.
• Dark mode is a separate palette. If dark mode is in scope, design both palettes in the style book. Don't invert at build time.

3b. Wireframe Review & Dashboard Detection

Text + ASCII layout sketches per screen: purpose, layout zones, key elements, states, navigation paths.

For each screen, declare:

• Primary question / action the screen serves (one sentence)
• Above-the-fold vs. scroll content
• Empty / loading / error / success states (all four)
• Responsive behavior at 375 / 768 / 1280px (or declare "desktop only" with reason)
• Navigation: where the top bar sits and what it holds at each breakpoint. A sidebar

here is a regression (Navigation rule above) — redraw it as a header before review

Data-heavy surfaces chain to oc-dash-forge. When a screen is data-heavy (≥3 charts/tables, real-time updates, BI/monitoring/analyst archetype, or rendering oc-data-ops' contracted marts), invoke oc-dash-forge per orchestrator.md §3:

1. Read oc-dash-forge/SKILL.md for the canonical archetype scoping table.
2. Invoke the Skill tool with skill "oc-dash-forge" and args "/oc-data-forge — <design tokens + spec context>", **and the Navigation

rule**: dashboards keep the top bar too, so reject a handoff whose shell is a sidebar.

1. Mark the screen source: oc-dash-forge and skip inline wireframes — oc-dash-forge's handoff bundle plugs into the Phase 3d punch list directly.

Non-data-heavy screens get wireframes generated inline using the Phase 3a token system.

3c. Wireframe Mockup Build

Interactive HTML prototypes: clickable navigation, real layout, realistic data, all states, responsive at 375/768/1280px.

Realistic data rule: Mock data must match the domain — real entity names, plausible distributions, realistic volumes. [1, 2, 3] arrays and "Customer A / B / C" are failure modes.

Skip for dash-forge-routed screens — they're handled separately.

★ Design Direction Approval Gate

Before asking for approval, confirm every screen's primary navigation is a top bar at 375 / 768 / 1280px. A direction with sidebar navigation is never presented — fix it first (Navigation rule; the only exception is a recorded nav_exceptions[] entry). Write checkpoint: phase "design-approved".

3d. Screen & Component Punch List

Exhaustive build checklist: every screen, component, variant, prop, state, interaction. The punch list IS the scope — if it's not listed, it doesn't get built.

For dashboard surfaces routed to oc-dash-forge, the punch list references the oc-dash-forge handoff bundle instead of re-specifying. Format:

Screen: Executive Compliance Dashboard
  Source: oc-dash-forge handoff at ./dash-forge-handoff/
  Components: see prototype.tsx + component inventory
  Integration: see integration-notes.md

★ Punch List Approval Gate

Write checkpoint: phase "punch-list-approved".

Phase 4: Sprint Plan (/oc-roadmap)

Convert the punch list and spec into an ordered sprint plan, saved to sprints/sprint-plan.md. Each sprint is a coherent, demoable chunk of work. One sprint plan, one format — used directly by Phase 6 build loop. For effort estimates and dependency ordering, references/phase-planning.md has the methodology.

Sprint Structure

## Sprint 1: [Name] — [Goal in one sentence]

### Features
[Which spec features / punch list items this covers]

### Deliverables
- [Specific things to build]

### Test Requirements
- Unit tests for: [core functions/endpoints]
- Integration test for: [key flow]

### Definition of Done
[Testable criteria the Evaluator will grade against]

### Dependencies
[What must exist before this sprint starts]

### Estimated Effort
CLAUDE: [hours] | USER: [hours]

Build Order

Sprints follow the design pipeline's build order:

1. Scaffold + design tokens + base components
2. Composite components + layouts
3. Screen pages from punch list
4. Navigation + routing
5. Backend hookup (auth → reads → writes → real-time → errors)
6. Polish + edge cases + accessibility

★ Sprint Plan Approval Gate

Write checkpoint: phase "sprint-plan-approved".

Phase 5: Scaffold (/oc-scaffold)

One-time project setup. Read references/scaffold-guide.md.

Generates: directory structure, package manifest, config files, .env.example, initial migrations, test infrastructure, CI/CD config, .gitignore, README with setup instructions.

Do NOT add `.checkpoints/` to `.gitignore`. The checkpoint directory is tracked in git on purpose — that's what lets session state survive across machines and clones (see references/checkpoint-protocol.md → Directory Convention). Ignore only .checkpoints/usage.sqlite* (oc-telemetry-ops' local metering DB) and .checkpoints/oc-bug-check.checkpoint.json (oc-bug-check runs fresh on every commit); commit every other *.checkpoint.json.

Scaffold must be immediately runnable after USER setup tasks (create DB, fill .env, etc).

Write checkpoint: phase "scaffold".

Phase 6: Build Loop (/oc-build)

This is the core of the skill. For each sprint from the sprint plan, run a Generator → Evaluator loop.

Build Configuration

Step 1: Sprint Contract Negotiation

Generator proposes a contract for the current sprint:

## Sprint [N] Contract

### Deliverables
- [Specific things to build]

### Testable Criteria
1. [Criterion]: [How to verify]

### Test Requirements
- [ ] Unit tests for: [list]
- [ ] Integration test for: [list]
- [ ] All tests pass before handing off

### Technical Approach
[Brief implementation plan]

Evaluator reviews and pushes back if:

• Criteria are vague or untestable
• Scope doesn't match the sprint plan
• Test requirements missing or insufficient
• Edge cases not covered

Iterate until aligned. Save to sprints/sprint-N/contract.md.

Step 2: Generator Builds

The Generator implements the sprint against the contract:

• Work through deliverables methodically
• Write tests DURING the build (not after)
• Minimum: 1 happy-path + 1 error-path test per function/endpoint
• Use project's test framework (set up Vitest/pytest if none exists)
• Mock external dependencies
• No snapshot tests, no framework-testing tests
• Self-check against contract before handing off (but don't self-grade)
• If hitting a wall, document the blocker

Step 3: Evaluator QA

The Evaluator grades the sprint against four criteria. It runs in the same session as the Generator, so its separation is a discipline, not a mechanism: re-read the contract and the code, and grade from those alone — not the generator's exploration.

Spawning an evaluator or reviewer. When the Evaluator runs as a subagent (an Agent spawn, a review lane) instead of inline, the spawn prompt opens with the tool-named invocation, before the checklist and the rubric. Not "use oc-code-auditor if available, else review manually": the 2026-10-08 audit measured that wording at 80/143 invocations (one lane 0/33) against 72/72 for this exact form.

Invoke the Skill tool with skill "oc-code-auditor" and args "/oc-audit diff --read-only <range>".
Then grade the sprint against the four criteria below.
Report format — first line: `skill_invoked: yes|no (<args as passed>)`;
second line: the findings artifact path (`audit/findings-<sha>.json`);
then the scores table and the verdict.

A report without the skill_invoked: line or the artifact path is INCOMPLETE, not a verdict. The read-only auditor writes the findings artifact plus a handoffs.verification.verdict entry in its own checkpoint and never runs the Fixer, so "the Fixer would modify the branch" is no longer a reason to skip it. On FAIL, ask the same reviewer for /oc-audit fix-all on a writable branch rather than bouncing the fix to another lane.

Test penalty: < 50% contracted tests delivered → Code Quality capped at 5/10.

Automated checks:

• Run full test suite → report pass/fail/skip
• Test failures → Functionality auto-capped at 5/10
• Check coverage if tooling exists. When .opchain/qa.yaml exists (written by

oc-qa-ops), grade new-code coverage against its coverage.new_code budget instead of an invented threshold; the <50%-contracted-tests penalty still applies independently (v1.9)

• Start dev server, hit endpoints
• Navigation check (UI sprints): load every changed screen at 375 / 768 / 1280px and

confirm primary navigation is the top bar. A sidebar or rail as primary nav → Visual/UX Quality capped at 3/10 and the verdict is FAIL, whatever the other scores (Navigation rule, Phase 3)

• Build errors, lint issues, type errors
• Read oc-code-auditor checkpoint for pre-existing issues

Manual review:

• Read code changes
• Check each contract criterion
• Look for stubs, TODOs, half-implementations
• Assess visual quality

UX Evaluator (a step you run on UI sprints — nothing attaches it for you): If the sprint contract mentions UI/component/screen/page, invoke oc-ux-engineer's Design Evaluator per orchestrator.md §3: read oc-ux-engineer/SKILL.md, check .checkpoints/oc-ux-engineer.checkpoint.json, execute /oc-uxe attach, and put its Design Scores in this round's report. It grades visual hierarchy, state completeness, consistency, and accessibility. Sprint must pass BOTH evaluators; oc-ux-engineer's standalone ITERATE verdict counts as FAIL here.

Evaluation report saved to sprints/sprint-N/eval-round-M.md:

## Sprint [N] — Evaluation Round [M]

### Code Scores
- Functionality: [X]/10 — [justification]
- Feature Completeness: [X]/10 — [justification]
- Code Quality: [X]/10 — [justification]
- Visual/UX Quality: [X]/10 — [justification]
- **Code Score: [X]/10** (weighted, informational — the gate is every criterion ≥ 6)

### Design Scores (if UI sprint)
- Visual Hierarchy: [X]/10
- State Completeness: [X]/10
- Consistency: [X]/10
- Accessibility: [X]/10
- **Design Score: [X]/10**

### Test Results
- Tests run: [X passed, Y failed, Z skipped]
- New tests: [count]
- Coverage: [X% or "not measured"]

### Bugs Found
1. [Bug with location and reproduction]

### Gaps vs Contract
1. [Criterion] — [PASS/FAIL] — [Evidence]

### Verdict: PASS / FAIL
[If FAIL: specific, actionable feedback]

Evaluator behaviors:

• Skeptical by default. Fight the natural tendency to approve mediocre work.
• Never approve "mostly works." Broken core feature = FAIL.
• Specific feedback: "header nav wraps to two lines at 768px because no min-width" not "UI needs work."
• Check the running app, not just the code.
• 5/10 means mediocre. Give it.

Step 4: Iterate or Advance

• PASS: Brief the user, advance to next sprint.
• FAIL + iterations remaining: Feed eval report to Generator, fix, re-evaluate.
• FAIL + max iterations: Escalate to user with all eval reports.

After each outcome: update the checkpoint, then publish the round's acceptance-check results as data, one line per sprint (a later round replaces the earlier one):

node scripts/checkpoint.mjs acceptance oc-app-architect --sprint sprint-N --verdict PASS|FAIL \
  --source sprints/sprint-N/eval-round-M.md --check AC-n.m=PASS --check AC-n.k=FAIL …

The check ids are the ### AC-n.m blocks of spec/06-testing.md that the sprint contract cites; --verdict is the report's verdict (PASS needs every check PASS). This is the acceptance.checks handoff a reader outside the loop (a client-side skill mapping sprints to milestones, a gate) validates with getCheckpointHandoff() instead of parsing the report. On PASS, when the sprint produced code, hand off to oc-git-ops: Skill(skill="oc-git-ops", args="/oc-commit — sprint-N passed its evaluator (sprints/sprint-N/eval-round-M.md)"). Record the round with its per-criterion scores, not just the aggregate, so a later session can tell whether the ≥ 6 gate was met: append to eval_scores[] an entry with rubric: "oc-app-architect", score (the weighted Code Score), max: 10, dimensions (functionality, completeness, quality, ux), and ref pointing at the eval report (see references/checkpoint-protocol.md → Wire 1.1 extensions).

Also keep one entry per sprint in skill_state.sprints[] — { "id": "sprint-N", "contract": "sprints/sprint-N/contract.md", "rounds": M, "verdict": "PASS|FAIL", "ux_eval_ref": …, "security_review_ref": … } — so a gate can read the two review refs without parsing eval reports:

• ux_eval_ref — the path of the oc-ux-engineer Design Evaluator report for this sprint

(the /oc-uxe attach output), or null with the reason ("no-ui").

• security_review_ref — the oc-security-auditor report (or the /oc-audit security

findings artifact) that covered this sprint's auth, secrets or personal-data changes, or null with the reason ("no-auth-or-data-change").

A UI sprint with ux_eval_ref: null, or a sprint that touched auth/secrets/data with security_review_ref: null, is not PASS, whatever the scores say.

Delegated lanes

Phase 6 is written for one session: one Generator, one Evaluator, one checkpoint writer. When a build is split across lanes (several sprints in parallel under a coordinating Master), these conventions apply instead of improvising:

• Prefer Agent subagents from one session. The Master spawns each lane as an Agent

subagent using the spawn template in Step 3; a lane's result is its report. Separate interactive sessions talking over SendMessage are the fallback, not the default — the 2026-10-08 audit counted 1,800+ approval-held messages in one week of that pattern.

• Per-lane checkpoints. A lane writes

.checkpoints/oc-app-architect.<lane>.checkpoint.json (same schema; phase and step ids only from this skill's frontmatter phases:, never invented ones) and never the Master file. The Master merges lane files into .checkpoints/oc-app-architect.checkpoint.json with checkpoint.mjs. The lane-merge subcommand is future work: until it lands the Master merges by hand, and the scripts/merge-checkpoint.mjs Git driver (installed by enrollment) keeps the lane files from producing false conflicts on PR.

• Lane↔Master traffic goes through checkpoint files, not messages. Sprint contract,

eval round, blocker and next_actions travel in the checkpoint per orchestrator.md §3 "Context Passing". State that exists only in a message is lost on resume.

• One reviewer verdict per PR. The review lane is /oc-audit diff --read-only <range>

with the Phase 6 criteria; its findings artifact and handoffs.verification.verdict are what the Master grades from, and a FAIL goes back to that reviewer for /oc-audit fix-all on a writable branch.

Scoring Calibration

Phase 7: Launch (/oc-launch)

Pre-Launch Pipeline

Chain through the launch pipeline per orchestrator.md §3. Each step actively invokes the next skill — read its SKILL.md, check its checkpoint, execute the command — rather than suggesting it:

1. oc-code-auditor — read oc-code-auditor/SKILL.md, execute /oc-audit pre-deploy. Block on CRITICAL/HIGH findings.
2. oc-security-auditor — read oc-security-auditor/SKILL.md, execute /oc-security posture. Block on CRITICAL findings.
3. oc-git-ops — read oc-git-ops/SKILL.md, execute /oc-git-sync. (oc-git-ops' own steps run oc-bug-check before commit, then the oc-docs-forge → oc-repo-ops pre-PR gate before opening the PR.)
4. oc-deploy-ops — read oc-deploy-ops/SKILL.md, execute /oc-deploy staging. After staging smoke-tests pass and user confirms, execute /oc-deploy prod.
5. oc-monitoring-ops — read oc-monitoring-ops/SKILL.md, execute /oc-monitor to wire post-deploy observability.

Launch Checklist

Write this list to checklists/launch-checklist.md and tick it off there.

• [ ] DNS configured
• [ ] SSL/HTTPS working
• [ ] Error monitoring live
• [ ] Database backups verified
• [ ] Rollback plan tested
• [ ] Environment variables set
• [ ] Rate limiting + CORS configured
• [ ] Analytics tracking verified
• [ ] README published
• [ ] User tested production URL
• [ ] Primary navigation is still a top bar on every screen (no sidebar regression)

Post-Launch

• Day 1: Monitor error rates
• Week 1: Review analytics, collect feedback, fix critical issues
• Week 2-4: Address feedback, plan v2
• Monthly: Dependency updates, security patches

Write checkpoint: status "complete".

Status Display

Shown on resume (Session Persistence → Resume on Start) and whenever the user asks "where are we?". Read checkpoint. Display compact status:

APP ARCHITECT — [project name]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Planning:
  ✅ Discovery
  ✅ Spec + oc-stack-forge (Next.js + Supabase)
  ✅ Design (style book + wireframes approved)
  ✅ Punch list (24 components, 8 screens)
  ✅ Sprint plan (4 sprints)

Build:
  ✅ Scaffold
  ✅ Sprint 1: Auth        8.2/10 (2 rounds) — 12 tests
  🔄 Sprint 2: CRUD API   eval round 1 in progress
  ⏳ Sprint 3: UI
  ⏳ Sprint 4: Polish

Next: Read evaluator report for Sprint 2
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

File Structure

project-dir/
├── .checkpoints/
│   └── oc-app-architect.checkpoint.json
├── spec/
│   ├── 00-project-overview.md ... 10-cost-estimate.md
│   └── 11-ai-architecture.md          (AI apps only)
├── design/
│   ├── style-book.html
│   ├── wireframes.html
│   ├── punch-list.md
│   └── component-registry.json        (written by oc-ux-engineer, when invoked)
├── sprints/
│   ├── sprint-plan.md
│   ├── sprint-1/
│   │   ├── contract.md
│   │   ├── eval-round-1.md
│   │   └── eval-round-2.md
│   └── sprint-2/ ...
├── checklists/
│   └── launch-checklist.md
├── src/ ...
└── master-spec.docx                   ("export the master spec")

Cross-Skill Integration

Every row is a step you run (orchestrator.md §3) — none of these fire on their own.

These skills also read this skill's spec files or checkpoint (protocol-public fields, never skill_state), whether or not this skill invokes them:

Quick Start Modes

Full pipeline (new project)

/oc-discover → /oc-spec → /oc-design → /oc-roadmap → /oc-scaffold → /oc-build → /oc-launch

From existing specs (oc-reverse-spec output)

/oc-roadmap → /oc-scaffold → /oc-build → /oc-launch

/oc-roadmap reads the spec docs from {project-dir}/spec/ (oc-reverse-spec's handoff puts them there and lists them in its context_primer.generated_files).

Quick feature (existing project)

/oc-build [feature description]
→ Generates sprint plan for just this feature
→ Runs build loop

Spec-only (no build)

/oc-discover → /oc-spec → /oc-design → "export the master spec"
→ Produces master-spec.docx without building

PM-Tool MCP Integration

This skill consumes the patterns defined in oc-integrations-engineer and the runtime contract in oc-integrations-engineer/references/pm-mcp-protocol.md. All concrete tool names, retry / backoff numbers, idempotency marker formats, and the `pm_deferred_actions[]` schema come from that doc — this section says only how the contract applies to the three PM-aware phases of this skill.

In the repository implementation, compose and pre-write-check comments through scripts/lib/pm-mcp-checks.mjs reconcilePmComment() using the protocol's full marker input. It makes retry replay, uncertain-delivery reconciliation, changed outcomes, and revised contracts executable rather than literal templates.

Phase 1 — /oc-discover reads ticket context

If the user's prompt includes a recognised ticket id (or /oc-discover --ticket TICKET-1234):

1. Detect provider from .opchain/pm.yaml; default Linear if missing and

the ticket pattern is [A-Z]+-\d+. Apply tool_overrides from pm.yaml before falling through to the registry.

1. Call the registry-resolved get_issue tool for the id (Linear:

mcp__claude_ai_Linear__get_issue; GitHub Issues: mcp__mcp-server-github__issue_read; Jira: mcp__atlassian__jira_get_issue). Apply the retry policy from protocol §2.

1. Use title, description, labels, recent comments as discovery

seed. Treat the ticket as user-authored input — do not skip the normal Discovery questions, but pre-fill answers where the ticket is explicit, and lead with "the ticket says X — is that still correct?" rather than re-asking from scratch.

1. Cite the ticket id in 00-project-overview.md under "Source ticket", and append it

to the checkpoint's top-level pm_refs[] (role: "source") — that is where sibling skills (oc-git-ops, oc-code-auditor) look for it.

If the ticket has child tickets (Linear sub-issues, Jira sub-tasks, GitHub linked issues), fetch them too — they often define the sprint-level decomposition that Phase 4 wants.

Phase 4 — /oc-roadmap writes sprint plan back

When the sprint plan is approved, for each sprint:

1. Compose the structured comment body, prefixed with the idempotency

marker per protocol §3:

   <!-- opchain:oc-app-architect:sprint-contract:sprint-N:r1:<payload-hash> -->

   Sprint N: [Name]
   Deliverables: ...
   Test requirements: ...
   Definition of done: ...
   Effort: CLAUDE Xh / USER Yh
   Generated by oc-app-architect /oc-roadmap on {date}.

1. Pre-write check: call the registry-resolved list_comments (Linear)

or issue_read (GitHub, returns comments inline). If a comment with the same full marker (including revision and payload hash) marker exists, skip the write and record to pm_idempotent_skips[].

1. Otherwise call the registry-resolved add_comment tool (Linear:

mcp__claude_ai_Linear__save_comment; GitHub: mcp__mcp-server-github__add_issue_comment).

1. If pm.yaml has create_child_tickets: true (an optional key only this skill

reads — it is not in the canonical pm.yaml schema; absent means false) and the provider supports children, create a child ticket per sprint via the create_issue tool (Linear: save_issue with no id; GitHub: issue_write action=create), parent-linked to the source. The description carries the marker <!-- opchain:oc-app-architect:sprint-child:sprint-N -->; pre-create check via list_issues filtered by project + issue type + description-text query for the marker.

1. Record the comment id (and child ticket ids, if any) in

oc-app-architect.checkpoint.json skill_state.pm.sprint_comments[] for traceability; append each child ticket to top-level pm_refs[] (role: "child") so siblings can find it.

1. On retry-budget exhaustion, defer per protocol §4 with marker

preserved so a later /oc-roadmap --retry-pm flush is idempotent.

Phase 6 — /oc-build updates sprint state

On each sprint pass / fail:

• Pass → resolve the done state string from pm.yaml.states

(do not hard-code), call the transition tool on the corresponding child ticket, then add_comment with marker <!-- opchain:oc-app-architect:sprint-result-pass:sprint-N:rN:<payload-hash> --> carrying the evaluator score.

• Fail (max iterations) → resolve blocked from

pm.yaml.states.extended (fallback: leave state unchanged and comment only); add_comment with marker <!-- opchain:oc-app-architect:sprint-result-fail:sprint-N:rN:<payload-hash> --> carrying the failure summary. A later pass has a distinct event marker and is therefore not suppressed; a retry of either unchanged delivery keeps its exact marker. Surface the user-facing escalation as usual.

--retry-pm flush

/oc-roadmap --retry-pm and /oc-build --retry-pm both invoke the protocol §4 flush sequence against oc-app-architect.checkpoint.json pm_deferred_actions[]. Filter to entries with skill: "oc-app-architect" and retriable: true. Surface a one-line flushed N / failed M summary to the user.

Failure modes

• No ticket reference in user prompt → skill runs without PM context (no

PM reads or writes). Never invents a ticket.

• MCP call fails (transient) → defer per protocol §4 with

retriable: true; user can /oc-roadmap --retry-pm later. Phase output is unchanged.

• Cross-team scope-violation (broker 403) → defer with

retriable: false, surface the permission error, never auto-flush. The spec docs and sprint plan are still produced locally.

Principles

1. Actionability > completeness. Every output answers "what do I build next?"
2. Gates in planning, loops in building. Planning needs human judgment (gates).

Building needs automated QA (evaluator loops).

1. One sprint plan, one format. No duplicate specs. No conflicting roadmaps.
2. Design before code. Catch UX problems in HTML prototypes, not React refactors.
3. Tests during the build. The Generator writes tests alongside code, not after.
4. Skeptical evaluation. The Evaluator's job is to find problems. 5/10 is fine.
5. Stack decisions happen inside Phase 2. Invoking oc-stack-forge is a Phase 2 step, not a separate project.
6. Checkpoint at every event. Session state survives across conversations.
7. Hand off, don't dead-end. Every phase suggests the next pipeline step.
8. Name assumptions. Hidden assumptions become hidden bugs.