The Eight Prime Directives

The following directives are NON-NEGOTIABLE and enforce the “Atomic Traceability” model:

Directive 1: Directory Supremacy

Every feature MUST have:

• An index.md entry point (the feature dashboard)
• A traceability.md matrix (requirement-to-task mapping)

Violation: Any feature lacking these files is considered incomplete and CANNOT proceed to implementation.

Directive 2: Atomic Injunction

The /atomicspec.tasks command is FORBIDDEN from creating a single tasks.md file.

It MUST create:

specs/[###-feature-name]/
├── index.md              # Feature dashboard
├── traceability.md       # Requirement-to-task matrix
└── tasks/                # Atomic task directory
    ├── T-001-[name].md
    ├── T-002-[name].md
    └── ...

Each atomic task file MUST contain:

1. ID: Unique task identifier
2. Requirement Mapping: Link to FR-XXX from spec.md
3. Technical Implementation Detail: Specific code actions
4. Verification Command: The exact test/command to verify completion

Directive 3: Context Pinning

During the implementation phase (/atomicspec.implement):

• You are FORBIDDEN from reading the full plan.md
• You may ONLY read:
  • index.md (for navigation and context)
  • The specific T-XXX-[name].md file assigned to the current task loop
  • traceability.md (to update status after completion)

Rationale: This prevents context pollution and ensures focused, verifiable execution.

Directive 4: Gate Compliance

You MUST strictly follow the “Gate Criteria” defined in .specify/knowledge/stations/ before transitioning between phases:

Violation: Proceeding without passing gates is a Constitution violation.

Directive 5: Knowledge Routing (The Map)

If you encounter a technical decision or edge case not covered by the current Task/Plan:

1. You MUST read .specify/knowledge/stations/00-station-map.md first.
2. Locate the correct Station ID for your problem.
3. Read ONLY that specific Station file.
4. Apply the rules found there.

Rationale: Do not guess. Do not read random files. Go to the authoritative source.

Directive 6: Human-In-The-Loop Checkpoints

During /atomicspec.plan, the AI MUST pause for user approval at critical decision points:

Phase 0.5 Checkpoint (Tech Stack Review):

After Phase 0 (Research) completes and before Phase 1 (Design) begins:

1. Present all resolved technical decisions in a table format:

   • Decisions explicitly from spec (marked “Spec”)
   • Decisions assumed by AI (marked “Assumed”)

2. Highlight assumptions that were NOT explicit in the spec but were inferred from:

   • Knowledge Station defaults
   • Best practices research
   • Domain patterns

3. PAUSE and wait for user response:

   • "proceed" → Continue to Phase 1 with current decisions
   • "revise: [specifics]" → Update decisions and re-present checkpoint
   • Questions → Answer and re-present checkpoint

4. Record approval in plan.md with timestamp

Rationale: Tech stack decisions are expensive to change post-implementation. Explicit user approval prevents rework and ensures alignment.

Violation: Proceeding to Phase 1 without user confirmation is a Constitution violation.

Skip conditions (checkpoint may be abbreviated):

• All Technical Context fields were explicit in spec (no assumptions)
• User passes --no-review flag (expert mode, assumes full responsibility)

Directive 7: Project Defaults Registry (Consistency Enforcement)

The Project Defaults Registry at specs/_defaults/registry.yaml is the single source of truth for project-wide technical decisions.

Scope of “registry-eligible decisions” (v0.2 clarification):

Registry-eligible decisions include not only the fields explicitly enumerated in registry.yaml, but any structural choice that pervades the codebase:

• Containerization (Docker / Compose / Kubernetes / none)
• Deployment target (containerized / serverless / VPS / PaaS / static)
• Monorepo vs. polyrepo layout
• File-structure pattern (feature-folder / layer-folder / domain-driven)
• Framework choice in any layer (backend, frontend, ORM, queue, cache, search, etc.)
• Cross-cutting infrastructure (payment provider, email provider, scheduling, file storage)
• Domain primitives (money representation, identifier exposure, time representation)
• Authentication / authorization model (session / JWT / OAuth2 / RBAC / ABAC / etc.)
• Logging and observability stack (structured logs, metrics, traces, error tracking)
• CI/CD platform and deployment workflow
• Package manager and runtime version pins
• Testing framework (unit / integration / E2E)

Definition of “commit”: writing config or code that encodes the choice (e.g., creating docker-compose.yml, adding a dependency to package.json, importing a framework module), OR recording the choice in plan.md or a task file as a fixed value. Drafting a comment that discusses options is not committing.

When the AI is about to commit to a structural decision absent from the registry, it MUST raise an AskUserQuestion before applying the decision, then offer to register the answer with provenance human or accepted_recommendation. This obligation is independent of the on-entry read step in the Protocol below — it fires whenever a qualifying decision arises, in any phase (/atomicspec.plan, /atomicspec.tasks, /atomicspec.implement). The “Docker-without-asking” failure mode (silently choosing a structural default) is a Directive 7 violation, not an unspecified blind spot.

ALL commands, agents, and phases MUST obey this protocol.

Registry Location:

specs/_defaults/
├── registry.yaml     # Source of truth (structured defaults)
├── changelog.md      # Audit trail (what/when/why/who)
└── README.md         # Documentation

Protocol - On Entry (Before Any Work):

1. Read specs/_defaults/registry.yaml
2. Filter to relevant sections (backend work → api, backend, database)
3. Apply registry values as non-negotiable defaults

Protocol - During Work (Decision Detection):

Protocol - On Exit (After Phase Completes):

1. Scan output for new project-wide decisions
2. Prompt user for each: “Add as project default?”
3. Update registry.yaml AND changelog.md if approved

Exemption — /atomicspec.constitution:

The /atomicspec.constitution command is formally exempt from the on-entry read step of this Directive. Rationale: the constitution authors the governance values that the registry later enforces — reading the registry before authoring them would be circular. Constitution MAY still write to the registry on exit if the user approves seeding default governance values (e.g., governance.quality_gates, governance.personas).

HITL Requirements for Registry Updates:

Every registry change MUST:

1. Go through AskUserQuestion - no silent updates
2. Provide clear explanation: what’s changing, why, impact
3. Allow user to: Accept / Reject / Provide custom value
4. Log in changelog.md with full audit trail:
   • Changed: old → new
   • Why: rationale
   • Source: which spec/phase
   • Approved by: Human (accept/custom/reject)

Deviation Documentation:

If a spec deviates from registry defaults, it MUST include:

DEVIATION from project-registry:
- Key: [key.path]
- Default: [registry_value]
- This spec uses: [different_value]
- Reason: [justification]
- Approved: Human (YYYY-MM-DD)

Violation: Using a value different from registry without explicit DEVIATION block and HITL approval is a Constitution violation.

Rationale: Prevents inconsistency (e.g., some APIs versioned, some not). Ensures all technical decisions are intentional and traceable.

Directive 8: Self-Contained Tasks (Knowledge Wiring)

Task files generated by /atomicspec.tasks MUST be self-contained. During implementation, Context Pinning (Directive 3) prevents reading plan.md, spec.md, stations, and subagents. Therefore, ALL context must be embedded INTO each task file.

Required Embedded Context Section:

Every task file MUST include an “Embedded Context” section containing:

Graceful Degradation:

Not all knowledge sources may exist. Handle gracefully:

NEVER fail task generation due to missing knowledge. Always produce tasks with whatever context is available.

Violation: Generating task files WITHOUT an Embedded Context section is a Constitution violation. The implementer must have EVERYTHING needed to complete the task without reading forbidden files.

Rationale: Subagents during /atomicspec.implement are “blind” to stations, subagents, plan.md, and spec.md. Embedding context ensures they follow project patterns instead of guessing.