AgentSkillsCN

kb

会话连续性的知识库。维护项目文档,采用固定目录结构(.pmc/docs/)和PRD、SOP、工单(T0000N)、模式、决策、代码地图、研究和状态的格式。 关键行为: 1. 首先查找——在任何任务之前,检查知识库中是否有现有文档(SOP、模式、代码地图、状态),这些可能指导工作。不要重新发明已记录的内容。 2. 学习=记录——当用户说“学习X”时,将其记录在适当的文档中: - 程序?→ 2-sop/ - 问题/解决方案?→ 6-patterns/(带状态:open|resolved) - 代码流程?→ 7-code-maps/ - 研究/笔记?→ 8-research/ - 设计决策?→ 5-decisions/D###-{name}.md - 用户澄清?→ 记录在工单5-final.md中 3. 捕获意图——当用户澄清需求或表达偏好时,在工单的5-final.md中记录(揭示意图部分)。 4. 收件箱——直接用户消息→ 0-inbox/供/pmc:dev或/pmc:plan稍后处理。 在以下情况下使用:设置文档结构、创建/管理工单、记录解决方案、映射代码流程、归档已完成工作、跟踪项目状态、捕获用户意图,或当用户要求“学习”某事时。

SKILL.md
--- frontmatter
name: kb
description: |
  Knowledge base for session continuity. Maintains project documentation
  with fixed directory structure (.pmc/docs/) and formats for PRDs, SOPs,
  tickets (T0000N), patterns, decisions, code maps, research, and status.

  CRITICAL BEHAVIORS:
  1. LOOKUP FIRST - Before any task, check kb for existing docs (SOPs, patterns,
     code maps, status) that may guide the work. Don't reinvent what's documented.
  2. LEARN = DOCUMENT - When user says "learn X", record it in appropriate doc:
     - Procedure? → 2-sop/
     - Problem/solution? → 6-patterns/ (with Status: open|resolved)
     - Code flow? → 7-code-maps/
     - Research/notes? → 8-research/
     - Design decision? → 5-decisions/D###-{name}.md
     - User clarification? → capture in ticket 5-final.md
  3. CAPTURE INTENT - When user clarifies requirements or expresses preferences,
     record in ticket's 5-final.md (Revealed Intent section).
  4. INBOX - Direct user messages → 0-inbox/ for later processing by /pmc:dev or /pmc:plan.

  Use when: setting up docs structure, creating/managing tickets,
  documenting solutions, mapping code flows, archiving completed work,
  tracking project status, capturing user intent, OR when user asks to "learn" something.

Knowledge Base

Manage project documentation with consistent structure and formats.

Quick KB Overview

Get the full docs structure:

code
Bash: ls -la .pmc/docs/                    # Top-level directories
Bash: find .pmc/docs -type d -maxdepth 2   # All directories (2 levels)
Bash: find .pmc/docs -name "*.md" | head -50  # First 50 markdown files

Or use Glob for specific areas:

code
Glob: .pmc/docs/*/                  # All top-level directories
Glob: .pmc/docs/**/*.md             # All markdown files

This quick listing is sufficient for initial KB loading - you don't need to read all files upfront.

Inbox (0-inbox/)

Task queue for messages from any source. Free-form format.

When to Use Inbox

SourceAction
Direct user message (not actionable now)Write to 0-inbox/{descriptive-name}.md
GitHub issue/PR notificationWrite to 0-inbox/ → ticket with GH# in 4-progress.md
Slack messageWrite to 0-inbox/ with context
Any external integrationWrite to 0-inbox/

GitHub Issues: Arrive via inbox → create ticket → track GH#N in 4-progress.md frontmatter and References section.

Inbox Format

Free-form. Include enough context for later processing:

markdown
# {Brief Title}

Source: {user/github/slack/etc}
Date: {YYYY-MM-DD}

{Content - can be any format from the source}

Processing

Inbox items are processed by /pmc:dev and /pmc:plan after completing their primary directive:

  1. Check 0-inbox/ for pending items
  2. Assess scope of each item
  3. Create appropriate artifacts (single ticket, phase, PRD, etc.)
  4. Remove processed items from inbox

Do not process inbox items during the primary workflow - only after completing the main task.

Core Workflow

1. LOOKUP FIRST (Before Any Task)

Before starting work, check existing documentation.

Why: Don't waste time rediscovering. If it's documented, use it.

2. LEARN = DOCUMENT (When User Says "Learn X")

When user says "learn how to...", "remember this...", "note that...":

What they learnedDocument in
How to do a task (commands, steps)2-sop/{verb}-{noun}.md
How to fix a problem6-patterns/{problem}.md (Status: resolved)
Known limitation/bug we can't fix6-patterns/{problem}.md (Status: open)
Workaround for issue6-patterns/{problem}.md (Status: open, with workaround)
Technical debt found6-patterns/{problem}.md (Status: open)
How code works7-code-maps/{feature}.md
Research, notes8-research/{topic}.md
Design/architecture decision5-decisions/D###-{name}.md
User preference/clarificationTicket 5-final.md (Revealed Intent)
Miscellaneous9-other/{topic}.md

Always create the doc immediately. Learning without documenting = lost knowledge.

3. UPDATE AFTER WORK

After completing tickets/tasks:

  • New pattern discovered? → 6-patterns/
  • Code flow mapped? → 7-code-maps/
  • Procedure refined? → 2-sop/
  • Useful research? → 8-research/

Design Principles

Why This Structure Exists

  1. Separation of concerns - Each directory has one purpose. PRDs define what, SOPs define how, plans track progress, etc.

  2. Discoverability - Descriptive filenames + glob/grep = no indexes needed (except tickets which use index.md as lookup table for number ↔ title mapping).

  3. Session continuity - I (Claude) lose context between sessions. Docs preserve state.

  4. Programmatic verification - JSON formats (tests) + status markers (5-final.md with BLOCKED | COMPLETE) allow scripts to track progress.

  5. Accountability - Paper trail of decisions, plans, and outcomes.

Document Hierarchy

code
PRD (feature-level)
 └── Phase (milestone)
      └── Ticket (implementable chunk)
           └── Tests (verification)
  • PRD defines the feature (what/why)
  • Phase groups tickets into milestones with E2E testing
  • Ticket is one implementable piece (1-3 days work)
  • Tests verify ticket completion

When to Use What

SituationAction
New feature ideaCreate PRD in 1-prd/
Breaking PRD into workPlan phases in 3-plan/roadmap.md
Starting implementationCreate ticket in tickets/ + add to roadmap
Repetitive procedureDocument in 2-sop/
Check project statusRead 4-status/features.md or 4-status/health.md
Made design/arch decisionCreate 5-decisions/D###-{name}.md
Solved a tricky problemDocument in 6-patterns/ (Status: resolved)
Found limitation we can't fixDocument in 6-patterns/ (Status: open)
Found technical debtDocument in 6-patterns/ (Status: open)
Explored codebaseDocument in 7-code-maps/
Research/notesStore in 8-research/
Miscellaneous docStore in 9-other/
User clarified intentCapture in ticket 5-final.md
Ticket/phase completeRun /pmc:reflect

End-to-End Workflow

Feature Implementation Flow

code
1. IDEA
   └── Create PRD: .pmc/docs/1-prd/feat-{name}.md

2. PLANNING
   └── Add to .pmc/docs/3-plan/roadmap.md
       ├── Single ticket? → Add under "In Progress" or "Next"
       └── Multiple tickets? → Create phase with E2E ticket

3. IMPLEMENTATION (per ticket, TDD mandatory)
   ├── Create ticket: .pmc/docs/tickets/T0000N/
   │   ├── 1-definition.md (what) → add to index
   │   ├── 2-plan.md (how)
   │   ├── 3-spec.md (technical details)
   │   └── 4-progress.md (Status: PLANNED)
   │
   ├── TDD CYCLE (repeat per behavior):
   │   ├── Write test: .pmc/docs/tests/tickets/T0000N/tests.json
   │   ├── RED: verify test fails (no implementation)
   │   ├── GREEN: implement minimal code to pass
   │   ├── REFACTOR: clean up, keep green
   │   └── Track in 4-progress.md (TDD Cycles section)
   │
   └── Complete: 5-final.md with Status: COMPLETE (or BLOCKED)

   Note: TDD opt-out only for trivial tickets (typo, config). Add "TDD: no" to constraints.

4. PHASE E2E (final ticket of phase)
   └── Live end-to-end testing of entire phase
       └── All tickets working together

5. PHASE COMPLETE
   ├── Archive tickets
   ├── Update .pmc/docs/3-plan/archive.md
   └── Update code maps if needed

6. REFLECTION (after ticket or phase) → use /pmc:reflect
   ├── Review session: what worked, what didn't
   ├── Update kb:
   │   ├── Pattern discovered? → 6-patterns/ (Status: resolved)
   │   ├── Open issue found? → 6-patterns/ (Status: open)
   │   ├── Decision made? → 5-decisions/D###-{name}.md
   │   ├── Code flow learned? → 7-code-maps/
   │   ├── Useful research? → 8-research/
   │   └── Repetitive procedure? → 2-sop/
   └── Capture learnings in 5-final.md "Learned" section

7. REPEAT for next phase

Git Worktree Integration

Directory Layout

code
project/                     # Main worktree (main branch)
├── .pmc/
│   ├── docs/                # Git tracked
│   └── data/                # Gitignored (runtime artifacts)
├── .worktrees/              # Gitignored (feature worktrees)
│   ├── T00001/
│   └── phase-1/
└── src/, tests/, ...

Branch Strategy

code
main
 └── phase/N
      ├── ticket/T00001
      ├── ticket/T00002
      └── ticket/T00003 (phase E2E)
TypeBranch PatternBase Branch
Phasephase/Nmain
Ticketticket/T0000Nphase/N

Phase Development Flow

1. Phase Start (main worktree)

bash
git checkout main
git checkout -b phase/1
git push -u origin phase/1

Update 3-plan/roadmap.md with phase tickets.

2. Ticket Implementation

Planning (main branch):

bash
git checkout main
# Create tickets/T00001/1-definition.md, 2-plan.md, 3-spec.md, 4-progress.md
git add .pmc/docs/tickets/
git commit -m "T00001: define ticket"

Implementation (ticket worktree):

bash
git worktree add .worktrees/T00001 -b ticket/T00001 phase/1
cd .worktrees/T00001
# Implement, update 4-progress.md
git commit -m "T00001: implement feature"
# Write 5-final.md with Status: COMPLETE
git commit -m "T00001: complete"
git push -u origin ticket/T00001

Merge to phase:

bash
git checkout phase/1
git merge ticket/T00001
git push
git branch -d ticket/T00001
git worktree remove .worktrees/T00001

3. Phase E2E

bash
git worktree add .worktrees/phase-1 phase/1
cd .worktrees/phase-1
# Run E2E tests, fix integration issues
# Write phase E2E ticket 5-final.md
git commit -m "T00003: phase 1 E2E complete"
git push

4. Phase Complete

bash
git checkout main
git merge phase/1
git push
# Archive tickets, update 3-plan/archive.md
git commit -m "phase 1: archive"
git worktree remove .worktrees/phase-1
git branch -d phase/1

Git Commit Points

Workflow StepBranchCommit Message
Ticket planningmainT0000N: define ticket
Implementation chunksticket/T0000NT0000N: {description}
Ticket completeticket/T0000NT0000N: complete
Phase E2E donephase/NT0000N: phase N E2E complete
Phase archivemainphase N: archive

Quick Reference: What Goes Where

I need to...Create in...
Define a new feature1-prd/feat-{name}.md
Plan phases/tickets3-plan/roadmap.md
Start implementingtickets/T0000N/
Document a procedure2-sop/{verb}-{noun}.md
Check feature status4-status/features.md
Track project health4-status/health.md
Record a decision5-decisions/D###-{name}.md
Save a solution6-patterns/{problem}.md (Status: resolved)
Track known issue6-patterns/{problem}.md (Status: open)
Map code flow7-code-maps/{feature}.md
Store research8-research/{topic}.md
Store misc docs9-other/{name}.md
Write teststests/tickets/T0000N/tests.json

Configuration

Default docs directory: .pmc/docs/ Override in CLAUDE.md: Docs directory: path/to/docs

Directory Structure

See references/directory-structure.md for the complete structure.

Quick summary:

code
.pmc/docs/
├── 0-inbox/        # Task queue from any source (free-form)
├── 1-prd/          # PRDs: feat-*, comp-*, infra-*
├── 2-sop/          # Procedures: {verb}-{noun}.md
├── 3-plan/         # roadmap.md, archive.md
├── 4-status/       # features.md, health.md, audits/
├── 5-decisions/    # D###-{name}.md (individual ADRs)
├── 6-patterns/     # Solutions/issues: Status: open|resolved
├── 7-code-maps/    # Feature traces
├── 8-research/     # Research & notes
├── 9-other/        # Miscellaneous free-form
├── tests/          # smoke/, core/, tickets/T0000N/
└── tickets/        # index.md, T0000N/, archive/

Discovery: Use Glob to list files, Grep to search content.

Document Formats

All format templates are in references/:

Read the relevant reference file before creating/editing any document type.

Maintenance Rules

  1. Update tickets index when creating/archiving
  2. Sequential numbering for tickets and decisions - never skip
  3. Archive, don't delete completed work
  4. Use templates exactly - keep formats consistent
  5. Update 3-plan/ on completion
  6. Use descriptive filenames - no index needed for other directories
  7. Keep code maps current - update 7-code-maps/ after ticket or phase completion
  8. REFLECT after every ticket - review session, update kb, capture learnings
  9. Branch from correct base - tickets from phase
  10. Clean up worktrees - remove after merge, don't leave stale worktrees
  11. Track decisions - create 5-decisions/D###-{name}.md when making design choices
  12. Update health - refresh 4-status/health.md after phase completion
  13. Capture intent - record user clarifications in ticket 5-final.md
  14. Use pattern status - mark 6-patterns/ as open (known issue) or resolved (solution)
  15. Resolve doc conflicts - when parallel work touches same doc (pattern, code-map), merge at phase boundary: compare versions, combine insights, note both sources