Skip to content
SiteSwarm Platform Documentation

Project Management And Intent Governance

Project Management & Intent Governance Runbook (PROJECT_MANAGEMENT_AND_INTENT_GOVERNANCE.md)

1. Executive Summary & Operational Intent

Autonomous AI engineering requires explicit governance boundaries to prevent five systemic failure modes:

  1. Unbounded Ticket Inflation: Spawning active roadmap tasks from casual remarks without founder ratification.
  2. Domain Boundary Bleed: Mixing technical architecture with retail pricing numbers ($/mo) or prescriptive legal/tax advice.
  3. Enterprise Spec Inflation: Designing premature enterprise complexity instead of minimal viable abstractions (MVA) with explicit deferred decisions.
  4. The “CI Green” Illusion: Equating passing mocked unit tests with verified runtime behavior.
  5. Anchored Research Spikes: Writing predetermined conclusions into research ticket descriptions before investigation begins.

This runbook establishes operational procedures for technical project management across SiteSwarm, reconciling directly with the Technical Project Manager skill (.agents/skills/pm/SKILL.md).

2. The 4-Horizon Backlog & Quarantine Model

SiteSwarm organizes all engineering intent into four discrete horizons:

flowchart LR
    H3["Horizon 3: Ideas & Deferred Decisions\n(Quarantined: needs-grooming)"] -.->|"Founder Ratification via pm groom"| H2["Horizon 2: Ratified Epics\n(Label: epic)"]
    H2 -->|"Decomposition & Criteria Backfill"| H1["Horizon 1: Shovel-Ready Tasks\n(4-Part Acceptance Criteria)"]
    H1 -->|"Worktree Dispatch via pm ship"| H0["Horizon 0: Active Execution\n(Label: status:in-progress)"]

2.1 The Quarantine Invariant (needs-grooming)

  • Whenever a new idea, potential future feature, or speculative architectural proposal is introduced during chat or review (“What if we…”, “Maybe down the road…”), it must be captured immediately as a GitHub issue labeled needs-grooming.
  • The Stop-Short Invariant: The agent must NEVER write application source code, spawn worktrees, or inject unratified ideas into active tickets in the same session.
  • Quarantined issues cannot be scheduled for autonomous execution until groomed and ratified by the founder via /pm groom or /grill-me.

2.2 Mandatory 4-Part Anti-False-Victory Acceptance Criteria

Every active implementation ticket must define four concrete sections before work begins:

  1. Functional Deliverables: Concrete component, schema, or system behaviors.
  2. Tier 1 (Machine Gate) Verification: Specific compilation, typecheck, and linter commands (pnpm run check, pnpm run lint:arch).
  3. Tier 2 (Behavioral Runtime Proof) Verification: Authentic CLI or HTTP execution proof (e.g. curl -I, Playwright E2E, exit code checks).
  4. Anti-Mocking & Failure-Mode Guardrails: Explicit declaration that mock-only testing fails the story, plus verification of error/edge handling.

3. Strict Domain Separation Invariants

SiteSwarm enforces strict separation between three domains:

  1. Technical Architecture (Engineering Domain): Governs code, schemas, capability identifiers, edge runtimes, and verification gates. Technical specifications and code must never hardcode retail pricing, monthly retainer figures ($/mo), or gross margin formulas.
  2. Commercial Strategy (Founder Domain): Pricing, packaging, and retainer agreements remain strictly outside technical architecture and code schemas.
  3. Legal, Tax & Entity Structure (External Expert Domain): Agents never issue prescriptive recommendations on business entity formation (LLC vs. S-Corp), compensation structures, or legal agreements; only neutral checklists for external CPA/counsel review are permitted.

4. Anti-Anchor Research Spikes & Minimal Viable Abstraction (MVA)

  1. Anti-Anchor Research Spikes (type:research / spike):
    • Research tickets must specify: (1) Unknown Question, (2) Decision Blocked, (3) Methodology, and (4) Objective Evaluation Criteria.
    • Negative Constraint: Never write predetermined answers or draft conclusions into research descriptions.
  2. Minimal Viable Abstraction & Deferred Decisions:
    • Design minimal flexible seams and intentionally defer premature complexity.
    • Every architectural specification and ADR must include an explicit ## Decisions Intentionally Deferred section so postponed complexity is tracked cleanly.

5. Core PM Operational Workflows

The PM engine provides standardized CLI and slash workflows for day-to-day project management:

Command Action Operational Protocol
pm resume Session Resume Scans active worktrees, uncommitted changes, in-progress tasks, and open PRs for a 15-second pickup briefing.
pm pause Session Handoff Saves local state, posts a checkpoint comment to the active GitHub issue, and provides an instant resume command.
pm ship #<N> Single-Task Execution Worktree-isolated task loop: implements deliverables, passes Two-Tier verification, opens linked PR, passes CI and Two-Stage Review, and cleanly reaps worktree.
pm merge <PR> Mechanical Pre-Merge Latch Audits review approvals (Stage 1 & Stage 2), checks CI, attests commit status check, and executes merge (pnpm run merge <PR>). Raw gh pr merge is banned.
pm groom #<N> Backlog Refinement Interactive design alignment via /grill-me, codebase exploration delegated to read-only subagent, and shovel-ready issue synthesis under strict issue-update boundaries.
pm fleet Parallel Fleet Dispatches parallel worker subagents across disjoint worktrees without merge collisions.
pm work Autonomous Delivery APDO delivery loop executing complete Planning Intervals (PIs) across multiple waves.

Decisions Intentionally Deferred

  • Automated cross-repository issue synchronization with external project trackers (Linear, Jira) is deferred; GitHub Issues serves as the authoritative project management store.