Skip to content

New Capability Checklist (Golden Standard)

This workflow defines the Capability-Driven Development (CDD) process. Every new feature or module must pass through these four "Tracks" to ensuring architectural consistency, security, and stability.

"If it's not in the Matrix, it doesn't exist."

1. Architecture Track (The Golden Books)

Defines the "What" and "Why" before code.

  • [ ] Domain Atlas: Update architecture/GOLDEN/03_DOMAIN_ATLAS.md.
  • Does the new module/subdomain exist in the Business Logic map?
  • [ ] Product Capabilities: Update architecture/GOLDEN/06_PRODUCT_CAPABILITIES.md.
  • Create a unique Capability ID (e.g., [OPS-HR-ROSTER]).
  • Define the Persona (Who), Trigger (When), and Success State (What).
  • Crucial: This ID will be used in code annotations.

2. Implementation & Architecture (Standard 106)

  • [ ] Code Implementation: Write the service/logic.
  • [ ] Capability Tagging: Add JSDoc @cap [ID] tags to the entry points.
  • Reference: Standard 106
  • [ ] Run MRI: Execute pnpm diagnose:mri to regenerate the Golden JSON.
  • [ ] Verify Matrix: Confirm your new ID appears in generated/capabilities.json.

3. Testing & Verifications

Connects the Backend to the Architecture.

  • [ ] Server Action: Create the actions/ file (e.g., actions/finance-procurement.ts).
  • [ ] Annotation: Tag the exported function with the Capability ID. 
    /**
 * @cap FIN-PROC-CONTRACT
 */
export async function createContractAction(...) { ... }
  • [ ] Safety Envelope: Ensure the action uses safeAction and requireUser.

3. Access Control Track (The Guard)

Connects the User to the Capability.

  • [ ] Audit Context: Is the capability meant for a specific role (e.g., Staff > Admin)?
  • [ ] Update Mapper: Edit apps/platform/src/lib/auth/capability-mapper.ts.
  • Add the Capability ID to the appropriate logic block (e.g., inside if (contexts.staff.department === 'admin')).
  • Example: caps['FIN-PROC-CONTRACT'] = true;
  • [ ] Verify: Ensure that without this mapping, the user effectively cannot access the feature (UI should hide, Action should reject if implementing verifyContext).

4. UI & Navigation Track (The Surface)

Connects the Human to the System.

  • [ ] Route Definition: Create the page at apps/platform/src/app/(app)/....
  • [ ] Navigation: Update messages/en.json (if using i18n nav) or the sidebar component.
  • [ ] UI Components:
  • List View: (e.g., ContractList.tsx) for reading data.
  • Editor/Form: (e.g., ContractEditor.tsx) for creating data.
  • [ ] Integration: Ensure the Page calls the Server Action (not mock data).

5. Verification Track (The Stamp)

Certifies the addition.

  • [ ] Verification Blueprint: (STND-102) Defined Persona, Success State, and Hazards during planning.
  • [ ] Type Check: Run pnpm type-check to ensure no schema breaks.
  • [ ] Capability Audit: Verified the @cap and @persona tags exist in the test header.
  • [ ] Manual Smoke Test:
  • Can I create the item?
  • Can I see the item?
  • Does it persist?
  • [ ] AutoTester: Run pnpm autotester:dev (Pre-Flight) successfully.