Imported from Onegaishimas/xcc_opencode (AGENTS.md). Install upstream with npx skills add Onegaishimas/xcc_opencode. Copyright stays with the author.

AGENTS Playbook — XCC Context Development Framework

Mission

Maintain a structured, resumable, documentation-first workflow for this project using the XCC framework in 0xcc/.

Operating Mode

• Prefer planning and documentation before implementation.
• Follow the document chain strictly: Project PRD -> ADR -> Feature PRD -> TDD -> TID -> Tasks -> Execution.
• Keep project state resumable at all times.

Mode Profiles

Choose the lightest mode that still controls risk.

1) Lite (small projects, prototypes)

• Required docs: 000_PPRD, one FPRD, one FTASKS
• Skip TDD/TID unless complexity grows
• Batch tasks and commit in larger chunks

2) Standard (default)

• Required docs: full chain (PPRD -> PADR -> FPRD -> FTDD -> FTID -> FTASKS)
• Use parent-task checkpoints and regular tests
• Best fit for most product work

3) Regulated (security/compliance-heavy)

• Full chain + stricter traceability in each doc
• Require explicit security, audit, and rollback sections
• Run validation and tests at every parent task boundary

Source of Truth

When framework docs conflict, use this precedence:

1. Current repository structure (0xcc/ folders and existing files)
2. 0xcc/instruct/000_README.md
3. Instruction files (0xcc/instruct/*.md)
4. This file (AGENTS.md) as active operational memory

Current Status

• Phase: Project Setup
• Active Document: None
• Current Feature: N/A
• Next Action: Create Project PRD using @0xcc/instruct/001_create-project-prd.md

Quick Resume

Use this at session start:

@AGENTS.md
@0xcc/session_state.json
ls -la 0xcc/*/

If project docs exist, also load:

@0xcc/prds/000_PPRD|[project-name].md
@0xcc/adrs/000_PADR|[project-name].md

Then load phase-specific folder:

• PRD work: @0xcc/prds/
• TDD work: @0xcc/tdds/
• TID work: @0xcc/tids/
• Task execution: @0xcc/tasks/

Workflow (Canonical)

Phase 1 — Foundation

1. Create Project PRD
   • Input: @0xcc/instruct/001_create-project-prd.md
   • Output: 0xcc/prds/000_PPRD|[project-name].md
2. Create ADR
   • Input: @0xcc/instruct/002_create-adr.md + Project PRD
   • Output: 0xcc/adrs/000_PADR|[project-name].md
3. Copy ADR "Project Standards" into this file.

Phase 2 — Feature Loop (repeat per feature)

1. Feature PRD -> 0xcc/prds/[###]_FPRD|[feature-name].md
2. Feature TDD -> 0xcc/tdds/[###]_FTDD|[feature-name].md
3. Feature TID -> 0xcc/tids/[###]_FTID|[feature-name].md
4. Feature Tasks -> 0xcc/tasks/[###]_FTASKS|[feature-name].md
5. Execute tasks using @0xcc/instruct/007_process-task-list.md

Instruction Map

• @0xcc/instruct/001_create-project-prd.md — Project PRD
• @0xcc/instruct/002_create-adr.md — ADR + standards
• @0xcc/instruct/003_create-feature-prd.md — Feature PRD
• @0xcc/instruct/004_create-tdd.md — Technical Design
• @0xcc/instruct/005_create-tid.md — Implementation guidance
• @0xcc/instruct/006_generate-tasks.md — Task generation
• @0xcc/instruct/007_process-task-list.md — Task execution protocol
• @0xcc/instruct/008_housekeeping.md — Session housekeeping and recovery

Tooling Policy

• Prefer tool-first operations: Read, Glob, Grep, and targeted edits before shell text processing.
• Use shell for execution tasks (tests, git, package managers, build commands), not primary file editing.
• Keep changes atomic and auditable: one concern per edit, predictable filenames, and explicit references.

Validation

• Schema reference: 0xcc/spec/003_SPEC_Document_Schemas.md
• Templates: 0xcc/templates/
• Run: python3 0xcc/scripts/validate_framework.py before PRs and checkpoints

Housekeeping Commands

"Please create a checkpoint"         # Save complete state
"Please help me resume"              # Restore context for new session
"My context is getting too large"    # Clean context, restore essentials
"Please save the session transcript" # Save session transcript
"Please show me project status"      # Display current state
"Please save session"                # Run full session housekeeping

"Please save session" Protocol

When prompted with "Please save session", perform this sequence:

1. Update Current Status and Next Action in AGENTS.md.
2. Create a checkpoint snapshot (framework state and active memory docs).
3. Save a session transcript summary.
4. Report what was saved and the next concrete action.

Project Standards

Replace this section after ADR generation.

Technology Stack

• Frontend: [TBD]
• Backend: [TBD]
• Database: [TBD]
• Testing: [TBD]
• Deployment: [TBD]

Development Standards

• Code organization: [TBD]
• Naming conventions: [TBD]
• API patterns: [TBD]
• Error handling: [TBD]
• Quality gates: [TBD]

Architecture Principles

• Security: [TBD]
• Scalability: [TBD]
• Observability: [TBD]
• Integration rules: [TBD]

Document Inventory

Project-Level

• ❌ 0xcc/prds/000_PPRD|[project-name].md
• ❌ 0xcc/adrs/000_PADR|[project-name].md

Feature-Level

• ❌ 0xcc/prds/[###]_FPRD|[feature-name].md
• ❌ 0xcc/tdds/[###]_FTDD|[feature-name].md
• ❌ 0xcc/tids/[###]_FTID|[feature-name].md
• ❌ 0xcc/tasks/[###]_FTASKS|[feature-name].md

Status legend: ✅ complete | ⏳ in progress | ❌ pending | 🔄 needs update

Task Execution Rules

• Work one sub-task at a time, but do not block on manual approval between every sub-task by default.
• Default execution style: complete a coherent batch under one parent task, then checkpoint with tests and status.
• Mark completion immediately: [ ] -> [x].
• When all subtasks under a parent are complete:
  1. Run tests
  2. Stage changes
  3. Remove temporary/debug artifacts
  4. Commit with conventional format
  5. Mark parent task complete
• Never commit with failing tests.
• Keep "Relevant Files" sections current in task docs.

Commit format:

git commit -m "feat: [brief description]" -m "- [key change 1]" -m "- [key change 2]" -m "Related to [Task#] in [PRD]"

Session Handoff Protocol

End of Session

1. Update Current Status in this file.
2. Save a checkpoint:
   • "Please create a checkpoint"
3. Save transcript (if needed):
   • "Please save the session transcript"
4. Record next concrete action.

Context Recovery

Mild loss:

@AGENTS.md
@0xcc/session_state.json
ls -la 0xcc/*/
@0xcc/instruct/[current-phase].md

Severe loss:

@AGENTS.md
@0xcc/prds/000_PPRD|[project-name].md
@0xcc/adrs/000_PADR|[project-name].md
ls -la 0xcc/*/
@0xcc/instruct/

Session Log

Session 1 — Project Initialization

• Accomplished: Created framework structure and initial project memory file
• Next: Create Project PRD via @0xcc/instruct/001_create-project-prd.md
• Files created: AGENTS.md, 0xcc/ structure

(Add one entry per session.)