# Pass the Parcel — Agent Entry Point

> **What this repo is.** Pass the Parcel is a template whose **goal** is **stateless, multi-agent planning & execution** — the 10-phase parcel pipeline with four hard gates and independent review. Its **principal instrument** is an **agent-first wiki** — a governed, grounded knowledge base (deterministic linter + Grounded Claims + drift automation) that keeps an agent's context cheap and honest — supported by **cache-first context**, **Managed Simplicity** and **deterministic guardrails**. This repo is the **template, not an app**: the app-facing content under `.wiki/` documents the pattern satellites fill in. See [`OPERATING-PRINCIPLES.md`](OPERATING-PRINCIPLES.md); maturity is tracked per axis in [`.devops/backlog/MATURITY.md`](.devops/backlog/MATURITY.md).

This repository is configured with a structured documentation library in **`.wiki/`** designed to serve as the single source of truth for the codebase, architecture, state management, and user interfaces.

### Documentation Structure
- **`.wiki/`** — Architecture knowledge, design system, features, and technical specs
- **`.devops/plans/`** — **Plans.** Claimed / in-flight `*-plan.md` only (`PHASE_1`+); template at `template-plan.md`
- **`.devops/sprints/`** — **Sprints (optional).** Active `sprint-{n}-<slug>/sprint.md` + the committed plan queue; indexed by `.devops/backlog/SPRINTS.md`; seeds ship in `.devops/templates/`; adopted by running `@sprint-plan`
- **`.devops/archive/`** — Completed plans (`*-plan.md` at root) + closed sprint records (`sprints/sprint-{n}-<slug>/sprint.md`)
- **`.devops/backlog/`** — **Backlog.** Master queue `backlog-index.md` (Themes table + Triage Panel), theme registers `t{n}-<slug>-backlog.md`, and parked `<code>-<slug>-backlog.md` plans (`claim_status: QUEUED`); commit via `@sprint-plan`, claim into `.devops/plans/`
- **`.devops/logs/`** — Agent changelog, version history
- **`.devops/skills/`** — All skills (SKILL.md per folder), loaded via `opencode.json` `skills` — the V2-native **flat array** (`[".devops/skills"]`). The live config is deliberately **mixed-dialect**: `skills` is V2-native while `agent` / `prompt` / `permission` stay V1-by-normalisation (V2 loads them by normalising, so they are left exactly as authored). JSON carries no comments, so the seed's own `_comment` records this where a bootstrapping maintainer meets it first.
- **`.devops/agents/`** — VS Code custom agents: `parcel.agent.md` + `parcel-sprint.agent.md` (orchestrators; `parcel-sprint` is the locked batch host) + `wiki-writer.agent.md` (selectable; `wiki-writer` is also subagent-invocable), `ptp-*.subagent.md` + `wiki-verifier.subagent.md` (subagents; `ptp-parcel-fast` is the hidden per-plan fast runner, spawned only by `parcel-sprint`)
- **`.wiki/rules/`** — Wiki governance layer — numbering, naming, frontmatter, doc-structure, link-hygiene, structure manifest + deterministic linter
- **`.wiki/rules/language/`** — Language governance layer — voice & tone, AI rules, publication rules
- **`.devops/rules/`** — Dev governance layer — agents & skills, plan lifecycle (canonical home of the plan lifecycle: [`.devops/rules/plan-lifecycle.md`](.devops/rules/plan-lifecycle.md))

Instead of searching the entire codebase to understand context, **STOP** and read the localized intelligence hub first.

---

## The Goal

**Pass the Parcel** is this template's purpose: turn a feature request into a reviewed, executed, verified change by passing one Markdown plan between specialised agents. It is stateless, independently reviewed, gated (A → B → C → D), and deterministic. The **agent-managed wiki** is the principal instrument; **Cache-first context**, **Managed Simplicity** and **deterministic guardrails** are the supporting instruments. Full statement: [`OPERATING-PRINCIPLES.md`](OPERATING-PRINCIPLES.md).

---

## Managed Simplicity

> **Managed Simplicity.** Every rule, skill, script and register is a purchase: climb the Simplicity Ladder before adding one, measure what exists with the surface-budget report, and retire what has stopped paying for itself — a drift gate is moved, never deleted. See `.devops/rules/managed-simplicity.md`.

---

## Design & Scope Notes

> [!NOTE]
> **This repo is the template, not an app.** The task-lookup rows that reference `src/components/ui`, screens, database queries, and CSV parsing are **satellite-facing examples** — they apply in workspaces that contain an application source tree. In this template they document the pattern satellites follow; there is no frontend or database here to edit.
>
> **Design lives in the wiki.** There is no separate `DESIGN.md` — `.wiki/core/09-design-system.md` is the single source of truth for visual design: creative North Star, core token table (`--color-surface`, `--color-primary`, …), typography, elevation, and component specs. Read it before creating or modifying any UI element, dashboard, or component.

---

## MANDATORY READING

Everything you need is mapped in `.wiki/`. Start at **`.wiki/core/00-system-index.md`** — it indexes the architecture flow and all feature-to-table mappings. For any specific task, use the lookup table below.

---

## TASK LOOKUP

| Task | Read first | Then drill into |
|------|------------|-----------------|
| Building or editing a UI component | `.wiki/components/components-index.md` | Specific component doc |
| Building or editing a screen / view | `.wiki/features/features-index.md` | Specific feature doc |
| Writing a database query | `.wiki/database/database-index.md` | Specific schema doc |
| Editing overall layout or workspace shell | `.wiki/core/07-app-structure.md` | Layout component docs |
| Understanding state shapes / context | `.wiki/core/04-state-context.md` | State management docs |
| Parsing or generating a CSV/XLSX import/export | `.wiki/logic/logic-index.md` | CSV Parser / xlsx utility |
| Extending a utility or custom hook | `.wiki/logic/logic-index.md` | Specific util/hook doc |
| Touching AI / agentic workflows | `.wiki/core/15-ai-features.md` | AI client utility |
| Checking backlog/roadmap or parked items | `.devops/backlog/backlog-index.md` | Specific backlog plan doc |
| Assessing template maturity / axis health | `.devops/backlog/MATURITY.md` | Specific axis evidence + next lever |
| Understanding what this template is / why it exists | `OPERATING-PRINCIPLES.md` | `README.md`, `.devops/backlog/MATURITY.md` |
| Viewing archived implementation plans | `.devops/archive/README.md` | Specific archived plan |
| Viewing audit results (T/F, Q&A, UI inventories) | `.devops/audits/README.md` | Originating skill doc |
| Adding or editing form fields | `.wiki/core/09-design-system.md` §5c | `.wiki/core/10-validation-standards.md` |
| Checking wiki health / link integrity | `@wiki-lint` skill | stdout report (soft, never blocks deploy) |
| Checking wiki evidence / claim drift | `scripts/wiki_claims.py check` | `.wiki/rules/claims.md` |
| Syncing the wiki after a code change | `@wiki-update` skill | `.wiki/rules/claims.md` |
| Generating wiki structure from code | `@wiki-generate` skill | `.wiki/core/17-docs-blueprint.md` |
| Asking a question about the codebase | `@wiki-query` skill | Cites `[Title](path)` from `.wiki/` + `ref/` |
| Recording a knowledge-capture decision | `@knowledge-capture` skill | `.wiki/core/18-knowledge-capture.md` |
| Adding to the backlog | `@backlog` skill | `.devops/backlog/backlog-index.md` + theme register |
| Auditing UI compliance | `@design-audit` skill | `.wiki/core/09-design-system.md` |
| Checking cross-view pattern consistency | `.wiki/core/18-knowledge-capture.md` (Domain Index) | `ptp-context-hunter` skill §2 + `ptp-grumpy-architect` skill §11 |
| Closing out a task | `@agent-wrap-up` skill | `.devops/logs/agent-changelog.md` |
| Multi-step planning | `@pass-the-parcel` skill | Parcel template at `.devops/plans/template-plan.md` |
| Running a whole sprint queue | `@sprint-run` skill | `.devops/skills/sprint-run/SKILL.md` |
| Choosing/editing subagent model bindings | `@model-routing` skill | `.opencode/plans/base-context.md` (Model Registry) |
| Pre-push validation (lint/test/build/push) | `@test-and-deploy` skill | `.devops/logs/version-history.md` |
| Syncing machinery / pulling template updates | `@sync-architecture` skill | `.devops/README.md` (Transportability) + HOW-TO.md §6 |
| Writing or editing code | `@karpathy-guidelines` skill | `.wiki/core/09-design-system.md` (if UI) |
| Reviewing agent operations history | `.devops/logs/agent-changelog.md` | git log for older history |

---

## Core Development Rules
1. **Never Hardcode Components:** Use the global variants inside `src/components/ui` (e.g., `<Button variant="primary">`).
2. **Never Hardcode Text Colors:** All text colors must use theme tokens (`text-primary-on` on `bg-primary`, `text-on_surface` for titles, `text-secondary` for labels). No `text-white`, `text-slate-*`, `text-gray-*`, or `text-black` in className strings. See `.wiki/core/09-design-system.md` §2, §5.
3. **Respect the Architecture:** Follow the project's data flow and domain constraints as documented in the wiki — do not bypass established patterns.
4. **Destructive Actions:** Use `<ConfirmModal>` for deletions. Ensure linked rows in dependent tables are properly managed.
5. **Context Review:** Before writing any code, review the last 3 entries in `.devops/logs/agent-changelog.md` to establish current project state.
6. **Subagent Wiki-First Mandate:** Any agent spawning a subagent (via `task`) MUST explicitly instruct that subagent to follow the wiki-first directive — STOP and read `.wiki/` before searching the codebase. Subagents spawned without this instruction will default to raw codebase search and waste context. This applies to all subagents regardless of role (planner, reviewer, surgeon, etc.).
7. **Planning Protocol:** Multi-step tasks MUST use the `@pass-the-parcel` skill.
8. **Form Field Hygiene (id + name + autoComplete + htmlFor):** Every `<input>`, `<select>`, and `<textarea>` MUST have an `id` attribute, and its corresponding `<label>` MUST have `htmlFor` matching that `id`. Auth forms (login/registration) additionally require `name` + `autoComplete` attributes for password manager support. For fields inside `.map()` loops, use globally unique dynamic IDs (e.g., `id={`field-${parentKey}-${index}`}`) — never a bare local index. See `.wiki/core/09-design-system.md` §5c for the full standard and common pitfalls.
9. **PREFIX-LOCKED Integrity:** `.opencode/plans/base-context.md` is the canonical shared prefix for all parcel/ptp agents. NEVER edit the inline prefix inside `.devops/agents/parcel.agent.md` or `.devops/agents/ptp-*.subagent.md` directly — edit `base-context.md`, then run `scripts\check-parcel-prefix.ps1 -Sync` to re-inline it byte-for-byte into every agent. Run `scripts\check-parcel-prefix.ps1` (and `scripts\check-utf8-agents.ps1`) before any push to verify no drift or encoding corruption. See `.opencode/plans/base-context.md`. **No agent declares a model:** every agent inherits the model selected in the CLI / picker, and the operator chooses subagent models at run time (`@model-routing` §3). The `## Model Registry` table is a **capability-class reference**, not a binding — a `model:` line in any agent frontmatter, an `agent.<key>.model` in `opencode.json`, or a third cell in a registry row fails the check. `@sync-architecture` reconciles the capability-class rows and **strips** any model it finds; it never stamps one. The check also fails on a registry key with no agent file, a binding file with no row, and a missing or empty `opencode.json` `agent` block.
10. **Chunked Write Discipline (large files):** Never materialise a large file in a single `write`/`edit` call — the editor runs a synchronous diff over the whole payload before the permission prompt and the TUI stalls on "Preparing write…". Create a skeleton first (frontmatter + section headings, each with a unique placeholder such as `<!-- FILL:goal -->`) in one small `write`; then fill each section with its own small `edit` that replaces that placeholder. Cap each call at roughly 60–100 lines and split larger sections beneath a sub-placeholder. `write` overwrites — it does not append — so never re-issue the whole payload; after a stall, `read` what landed and continue with the next section. This applies to every agent and subagent, including plan/sprint/doc authoring.
11. **User-Facing Conversation:** User is the Product Owner, Agent is the Dev — the owner sets the direction and owns the vision; the dev team owns the technical and reports back in the owner's language: plain words, outcomes first, no unexplained jargon. See `.wiki/rules/language/communication-rules.md` § User-facing conversation.

---

## Governance Layers

- [`.wiki/rules/`](.wiki/rules/README.md) — how the wiki is structured, named, linked (`python scripts/wiki_lint.py` enforces it deterministically)
- [`.wiki/rules/language/`](.wiki/rules/language/README.md) — how we write — voice, tone, evidence, audience
- [`.devops/rules/`](.devops/rules/README.md) — how agents, skills, plans and operational state are governed
- [`.devops/`](.devops/README.md) — operational state + the transportable machinery layer (skills, agents, plans, logs)

---

## Wrap-Up Protocol

Use the `@agent-wrap-up` skill when a task is complete.