Convention Index

This document is the central entry point for the implementation-playbook style conventions in the Context-Action repository. The docs have grown enough that it helps to group which documents define the rules, which ones demonstrate the pattern, and which ones lock the verification model.

Start Here by Task

Choose the path that matches the change; do not read the whole library before you know which artifact you own.

If you are changing…	Read first	Then use
a package responsibility, dependency, or export	Package Boundary and Codebase Management	pnpm package-boundary:check
a public guide, API reference, README route, or generated document	Documentation and Development Management	pnpm docs:check
a durable architectural boundary or compatibility exception	Architecture Decision Records	the linked package/guide and focused proof
a feature, bug, or workflow contract	Specification, Issue, and Documentation Management	its change-class gate
a canonical example/usecase	Implementation Convention	pnpm convention:check and example checks

For a release candidate, use pnpm verify:all; it composes the repository checks rather than replacing focused evidence.

Grouped by Role

1. Documents that define the standard

• Convention Alignment Plan
  • current-state classification, fixed provider order, and migration gates
• Package Boundary and Codebase Management
  • package ownership, dependency direction, package lifecycle, and cleanup rules
• Mutative Core History and Upstream References
  • Mutative source lineage, carried upstream fixes, licensing, and synchronization rules
• Implementation Convention
  • the standard implementation-playbook rule set
• Core Action Contracts
  • framework-neutral dispatch, lifecycle trace, and action-to-state boundary
• React State Contracts
  • Store reader/writer roles, safe reads, transactions, timeline, and inspector boundary
• Specification, Issue, and Documentation Management
  • issue lifecycle, contract traceability, decision records, and handoff evidence
• Architecture Decision Records
  • durable home and template for package, protocol, persistence, and compatibility decisions
• Tool-Calling Web Studio Convention
  • tool registry, policy, workspace mutation, observable subscriptions, and live preview boundaries
• Panel Layout Preference Convention
  • presentation-only panel state, bounded resizing, persistence, and Store Context promotion criteria
• Tool-Calling Editor Architecture
  • detailed catalog, approval, trace, persistence, and preview reference implementation
• Folder Structure
  • responsibility split across contexts / business / handlers / actions / hooks / views
• Handler Registry
  • handler registration and separation rules

2. Documents that explain logic and transitions

• Explicit State Machine
  • how to lock complex async flows as state + event + transition
• Context-Layered Overview
• Usecase and Recipe Profile
  • the high-level architectural picture
• Integration Profiles
  • versioned external-domain lifecycle, ownership, compatibility, and evidence catalogs
• Migration Guide
  • how to move older structures into this model

3. Documents that demonstrate the implementation

• Canonical Order Form Example
  • the base canonical example
• Access Request Playbook Example
  • approval/review workflow example
• Incident Escalation Playbook Example
  • incident/escalation workflow example
• Renewal Risk Review Playbook Example
  • renewal/customer-success workflow example
• Playbook Scenario Library
  • scenario extensions that follow the same skill and convention

4. Documents that define verification

• Stability Test Cycle
  • how to split contract tests, scenario tests, and stress validation
• Next Work and Documentation Ownership
  • the single backlog and source-of-truth map for follow-up work

The general repository convention gate is:

pnpm convention:check

For the complete Context-Action integration gate, run:

node scripts/verify-context-action-conventions.mjs

It adds the example use-case recipe, MCP/function-calling catalog, integration-profile catalog, and standalone Web Studio action boundaries. Use pnpm web-coding:verify for the standalone build, filesystem, provider, preview, and browser release checks.

Reading Paths by Goal

For architecture alignment

1. Implementation Convention
2. Specification, Issue, and Documentation Management
3. Explicit State Machine
4. Stability Test Cycle

For a stateful action that updates more than one Store, read the Core Action Contracts and React State Contracts together. Core emits dispatch traces but never infers Store ownership; the React layer opens an explicit transaction with named participants.

For implementer onboarding

1. Canonical Order Form Example
2. Access Request Playbook Example
3. Incident Escalation Playbook Example
4. Renewal Risk Review Playbook Example

For designing new scenarios

1. Playbook Scenario Library
2. Implementation Convention
3. repo-local skill: skills/context-action-implementation-playbook/SKILL.md

For tool-calling web studios

1. Tool-Calling Web Studio Convention
2. Specification, Issue, and Documentation Management
3. Panel Layout Preference Convention
4. Tool-Calling Editor Architecture
5. Standalone Web Studio README

Read Alongside the Example App

The docs make more sense when paired with the live demos:

• /patterns/implementation-playbook
• /patterns/implementation-playbook/access-request
• /patterns/implementation-playbook/incident-escalation
• /patterns/implementation-playbook/renewal-risk-review
• standalone /web-coding/ release

One-Line Summary

Choose the source of truth first, make the smallest matching change, update only its derived artifacts, and run the gate that proves that boundary.