tendril/docs/PHASE-UPDATES/COMPLETE-SYSTEM-REPLICATION-GUIDE.md

Complete System Replication Guide

Comprehensive Documentation System for Cursor + LLM Projects

Purpose: This document contains everything needed to replicate the PAIRS documentation and automation system in another project. It includes all structures, schemas, templates, rationale, and step-by-step instructions.

Last Updated: 2025-01-27

---

Table of Contents

1. System Overview
2. Cursor Rules System
3. Phase Documentation System
4. Knowledge Base (KB) System
5. GitHub Automation System
6. LLM Usage Guides
7. Schemas and Validation
8. File Structure and Conventions
9. Decision Rationale
10. Step-by-Step Replication Guide
11. Templates
12. Troubleshooting

---

System Overview

What This System Provides

This documentation system creates a comprehensive, LLM-friendly project structure that includes:

• Phase-based project management with synchronized documentation
• Knowledge Base (KB) system for capturing and organizing external information
• Automated workflows via GitHub Actions
• Cursor rules for consistent AI agent behavior
• LLM usage guides for prompt-based workflows
• Decision tracking via ADRs (Architecture Decision Records)
• Change tracking via changelogs
• Task management synchronized with GitHub issues

Core Principles

1. Documentation is the Single Source of Truth - Always read phase blueprints before making changes
2. Synchronization is Mandatory - Related documents must stay in sync automatically
3. LLM-Friendly Structure - All documentation is structured for AI agent consumption
4. Incremental Updates - Update documentation as you work, not at the end
5. Validation at Every Step - Automated validation ensures consistency

System Architecture

Project Root/
├── .cursorrules              # Main Cursor rules file
├── .cursor/rules/            # Individual Project Rules (alternative)
├── .github/                  # GitHub Actions and automation docs
│   ├── workflows/            # GitHub Actions workflows
│   ├── README.md             # .github directory overview
│   ├── CHANGELOG.md          # Workflow change tracking
│   ├── decisions.md         # Automation decisions
│   └── LLM-Usage-Guide--{REPO}.md  # Per-repo LLM guide
├── docs/                     # Project documentation
│   ├── AGENT-GUIDELINES.md   # AI agent rules
│   └── PROMPTS/              # LLM prompt documents
├── pairs/                    # Main project directory (customize name)
│   ├── phases/               # Phase documentation
│   │   └── phase-XX-name/
│   │       ├── blueprint.md  # Phase blueprint
│   │       ├── tasks.md      # Task tracking
│   │       ├── decisions.md # ADRs
│   │       └── changelog.md  # Change history
│   └── research/             # Research materials
└── kb/                       # Knowledge Base system
    ├── 01_projects/          # Project-specific notes
    ├── 02_systems/           # Infrastructure/tooling
    ├── 03_research/          # Informal research
    ├── 04_design/            # Product specs/UX
    ├── 05_decisions/         # Project-level ADRs
    ├── 06_glossary/          # Terms/acronyms
    ├── 07_playbooks/         # How-to guides
    ├── 08_archive/           # Superseded content
    ├── _guides/              # KB system guides
    ├── _templates/           # KB file templates
    ├── _inbox/               # Unclassified content
    ├── _review_queue/        # Low-confidence routing
    ├── _index.md             # Auto-generated index
    └── scripts/              # KB automation scripts

---

Cursor Rules System

Overview

Cursor rules control how AI agents (like Cursor AI) behave in your project. There are two approaches:

1. Single .cursorrules file - Traditional approach, all rules in one file
2. Project Rules (.cursor/rules/*.mdc) - Modern approach, individual rule files

Approach 1: Single .cursorrules File

Location: .cursorrules (root of repository)

Complete Content (with annotations):

# Cursor Rules for [PROJECT NAME]

## Phase Documentation Synchronization Rules

### MANDATORY: When blueprint.md is modified, automatically update related phase documents

When ANY file matching `pairs/phases/phase-*/blueprint.md` is edited or updated:

1. **ALWAYS check and update `changelog.md`** in the same phase directory:
   - Add a new entry with today's date (YYYY-MM-DD format)
   - Describe what changed in the blueprint
   - Use format: `- **YYYY-MM-DD:** [Description of change]`

2. **ALWAYS check and update `tasks.md`** in the same phase directory:
   - Sync task checkboxes with "Definition of Done" items from blueprint
   - Sync task list with "Phase Deliverables" section from blueprint
   - Ensure task status aligns with milestone statuses in blueprint
   - Update phase status if blueprint status changed

3. **ALWAYS check `decisions.md`** in the same phase directory:
   - If blueprint changes reflect new architectural decisions, add ADR entry
   - If decisions are mentioned in blueprint but not in decisions.md, add them
   - Review that existing ADRs still align with blueprint specifications

4. **ALWAYS verify consistency**:
   - Project name matches across all phase documents
   - Dates are consistent (or marked as TBD consistently)
   - Team roles match where applicable
   - Status indicators are aligned

#### When GitHub Actions workflows (`.github/workflows/*.yml`) are modified:

1. **ALWAYS update `.github/CHANGELOG.md`**:
   - Document workflow changes, new triggers, or automation updates
   - Note any changes to scheduled times or conditions
   - Include affected workflow name and file path

2. **ALWAYS update `.github/decisions.md`** (if decision-related):
   - Document the decision behind the workflow change
   - Explain rationale and alternatives considered
   - Note impact on automation

3. **ALWAYS update `.github/README.md`** (if structure or behavior changed):
   - Update workflow descriptions if behavior changed significantly
   - Add new workflows to overview section
   - Remove references to deleted workflows

4. **ALWAYS verify workflow references**:
   - Check that documentation references to workflows use correct file names
   - Ensure workflow descriptions in docs match actual workflow logic

#### When `.github/` folder is modified (any file):

1. **ALWAYS update `.github/CHANGELOG.md`**:
   - Document all changes to .github folder structure
   - Include file paths and what changed
   - Note if workflows, documentation, or structure was modified

2. **ALWAYS update `.github/decisions.md`** (if decision-related):
   - Document decisions about .github folder structure
   - Explain rationale for documentation organization
   - Note impact on workflow maintenance

3. **ALWAYS update `.github/README.md`** (if structure or purpose changed):
   - Update overview if folder structure changed
   - Update workflow descriptions if documentation changed
   - Ensure all workflows are listed in overview

### Specific Blueprint Change Triggers

When blueprint.md changes include:
- **Project name change** → Update all phase documents to reflect new name
- **Milestone status changes** → Update tasks.md and changelog.md
- **Deliverables completion** → Update tasks.md checkboxes and changelog.md
- **Team role assignments** → Update changelog.md if significant
- **Timeline changes** → Update changelog.md with reason
- **Scope changes** → Update decisions.md if architectural decision involved
- **Status changes** → Update tasks.md status line

### Workflow for Blueprint Updates

1. After editing blueprint.md, immediately:
   - Read changelog.md, tasks.md, and decisions.md from the same phase directory
   - Compare blueprint content with related documents
   - Identify discrepancies or missing updates
   - Update all related documents to maintain consistency
   - Verify no information is lost (only added or synchronized)

2. Before completing any blueprint edit session:
   - Confirm all related documents have been checked
   - Confirm all necessary updates have been made
   - **ALWAYS provide a summary** of what was updated:
     * List each file that was modified
     * Describe what changes were made to each file
     * Note any files that were checked but didn't need updates
   - **ALWAYS ask the user** if they want to push these changes to the remote repository

### Never Skip These Steps

- ❌ **NEVER delete files or folders when committing or pushing to the repository**
- ❌ NEVER edit blueprint.md without checking related documents
- ❌ NEVER leave related documents out of sync
- ❌ NEVER assume related documents are already updated
- ✅ ALWAYS read related documents before making changes
- ✅ ALWAYS update related documents in the same session
- ✅ ALWAYS verify consistency across all phase documents

## General Project Rules

- Always read phase blueprints before making changes
- **CRITICAL: NEVER delete files or folders when committing or pushing**
  - **UNDER NO CIRCUMSTANCES** are you to delete files or folders whenever the user requests for you to commit from the local repo or push to the remote repo
  - Commits and pushes should only include file modifications, additions, and updates
  - If file deletion is needed, it must be explicitly requested by the user in a separate, clear request
  - Never perform cleanup, organization, or deletion operations as part of commit/push workflows
- Update documentation incrementally, not at the end
- Follow the structure defined in `docs/AGENT-GUIDELINES.md`
- Use conventional commit messages with phase references

## KB Ingestion & Routing Rules

### MANDATORY: KB Ingestion System Behavior

When the chat starts with the text "SYSTEM — KB Ingestion & Routing" (from `/kb/_guides/KB_INGEST_PROMPT.md`), treat it as a system message and follow KB ingestion protocols.

### KB Write Scope & Constraints

**Assistant Rules:**
- Only create or update files under `/kb` except when explicitly asked otherwise
- Never modify files in `/kb/_guides` or `/kb/_templates`
- Enforce the filename pattern: `^\d{4}-\d{2}-\d{2}--[a-z0-9-]{3,}--(idea|note|spec|decision|howto|retro|meeting)\.md$`
- Before writing KB files, ensure YAML frontmatter contains all required keys: `title`, `date`, `captured_at`, `author`, `source`, `source_type`, `project`, `related_projects`, `topics`, `tags`, `type`, `status`, `phase_relevance`, `routing_hint`, `proposed_path`, `routing_confidence`, `related`, `summary`
- Include project-specific fields: `captured_at` (same as date), `source_type` (voice|web|pdf|image|personal_note|chat|pulse), `related_projects` (same as project), `phase_relevance[]` (array of phase-XX or empty)
- Optional fields: `key_takeaways[]`, `action_candidates[]`
- If the user pastes multiple unrelated chunks, split into separate files (max 5) and suffix with `--p1`, `--p2`, etc.
- If routing is ambiguous, write to `/kb/_inbox` and include `routing_hint` explaining uncertainty
- Respond with a single JSON code block as specified by the KB ingestion system prompt
- Default `author` is `["unknown author"]` if not specified
- Default `project` is `[project-name]` - customize for your project

**User Guidelines:**
- Provide raw content after the system prompt
- Avoid mixing unrelated topics when possible
- Paste `/kb/_guides/KB_INGEST_PROMPT.md` contents as the first message in a Cursor chat before pasting any material

### KB System vs Research System

**When to use KB system (`/kb/`):**
- Pulse Daily chats and ideas
- Informal notes and thoughts about the project
- External information that may inform the project
- Project-level decisions (complements phase-specific ADRs)
- How-to guides and playbooks
- Glossary entries
- Design ideas and UX concepts

**When to use Research system (`pairs/research/notes/` or equivalent):**
- Formal research articles, papers, and web content
- Content that will be actively researched and indexed
- Research materials that go through ingestion pipeline
- Content requiring full research metadata schema

**Integration:**
- KB entries can reference project phases via `phase_relevance[]` field
- KB decisions complement (not replace) phase-specific ADRs
- KB entries use aligned metadata schema for compatibility

### KB Workflow Maintenance

**When KB structure or guidelines change:**
- Check and update GitHub Actions workflows (`.github/workflows/kb-lint.yml`) if KB validation rules change
- Check and update README.md if KB system is added or significantly modified
- Ensure workflows stay in sync with KB guidelines in `/kb/_guides/`

### KB Index Check Requirements

**MANDATORY: Pre-Planning KB Check**

Before starting any planning or development work, ALWAYS:

1. **Read `kb/README.md`** to understand the KB system (if first time working with KB)
2. **Read `kb/_index.md`** to check for relevant KB content
3. **Search `kb/_index.md`** for keywords related to current task:
   - Check topics index for relevant topics
   - Check tags index for relevant tags
   - Search file titles and summaries
   - Check relevant categories (e.g., decisions, specs, research)
   - Check phase relevance index for content related to current phase
4. **If relevant KB content found:**
   - List specific KB files that might be relevant (with paths from index)
   - Summarize relevant entries from index (title, summary, topics, tags, phase relevance)
   - Ask user if they want to incorporate KB knowledge into current work
   - If user confirms, read the actual KB files referenced in index
   - Reference KB files in documentation or code comments when appropriate

**KB Index and Changelog Update Requirement**

**MANDATORY:** After creating, modifying, or deleting ANY file in `kb/` (except `_guides/`, `_templates/`, `README.md`, `_index.md`, and `CHANGELOG.md`):

1. **Run index generation script:**
   ```bash
   kb/scripts/generate-index.sh

• This regenerates kb/_index.md with current KB content
• Verify the script completes successfully
• Check that changes appear in kb/_index.md

2. Update KB changelog:

   • Add entry to kb/CHANGELOG.md with date-based format:

     ## [YYYY-MM-DD] KB File Added/Modified/Deleted
     
     ### Added/Changed/Removed
     - `kb/XX_category/filename.md` - [Brief description]
     

   • Use today's date (YYYY-MM-DD format)
   • Include the full file path relative to repository root
   • Provide a brief description (1-2 sentences) of what changed

3. Commit all changes together:

   • Commit KB file change, index update, and changelog entry together
   • Use commit message: docs(kb): [action] [filename-slug] and update index/changelog
   • Examples:
     • docs(kb): add api-auth-decision and update index/changelog
     • docs(kb): update cursor-workflow and update index/changelog
     • docs(kb): remove obsolete-note and update index/changelog

4. Note: GitHub Actions will auto-update index on push to main, but local updates should also regenerate index. Changelog updates are always manual and must be done locally.

NEVER skip these steps - Both index and changelog updates are mandatory for KB system integrity.

README Maintenance Rules

MANDATORY: Check and Update README After Work Completion

After completing ANY work session that involves:

• Phase blueprint updates
• Phase status changes
• New deliverables or features
• Directory structure changes
• Project name or description changes
• Major architectural decisions

You MUST:

1. Read the current README.md to understand its current state

2. Check if updates are needed by verifying:

   • Phase statuses are accurate (✅ Complete, 🔄 In Progress, ⏳ Planned)
   • Phase names match current blueprints
   • Directory structure reflects actual project layout
   • Links to phase blueprints are correct
   • Project description matches current state
   • Getting Started section is accurate

3. Update README.md if any of the following changed:

   • Phase status (e.g., Phase 1 moved from Planned to In Progress)
   • Phase names or descriptions
   • Project structure (new directories, renamed files)
   • Project name or branding
   • Key features or capabilities
   • Documentation links or paths

4. Before completing work session:

   • Confirm README.md has been checked
   • Update README.md if needed
   • Verify all links in README.md are valid
   • Ensure README.md accurately reflects current project state

Never Skip README Updates

• ❌ NEVER complete work without checking README.md
• ❌ NEVER leave README.md out of sync with project state
• ❌ NEVER assume README.md is already up to date
• ✅ ALWAYS check README.md after making significant changes
• ✅ ALWAYS update README.md when phase statuses change
• ✅ ALWAYS verify README.md accuracy before committing

### Approach 2: Project Rules (`.cursor/rules/*.mdc`)

**Location**: `.cursor/rules/` directory

**File Format**: Each rule is a separate `.mdc` file with frontmatter

**Example Rule File** (`.cursor/rules/phase-documentation-workflow.mdc`):

```markdown
---
alwaysApply: true
---
When editing any phase blueprint.md, immediately check and update: changelog.md, tasks.md, and decisions.md in the same phase directory. Always verify project name consistency across all phase documents. Update README.md phase statuses when phase status changes (✅ Complete, 🔄 In Progress, ⏳ Planned).

Individual Rules to Create:

1. phase-documentation-workflow.mdc

   • Content: Phase documentation synchronization rules

2. kb-system-usage.mdc

   • Content: KB system usage and index check requirements

3. file-structure-conventions.mdc

   • Content: File naming and structure conventions

4. commit-message-standards.mdc

   • Content: Conventional commit message format

5. adhd-friendly-workflow.mdc

   • Content: Break work into small chunks, incremental updates

6. github-automation-maintenance.mdc

   • Content: .github folder update requirements

Setup Instructions:

1. Create .cursor/rules/ directory in project root
2. For each rule, create a .mdc file with:
   • Frontmatter: ---\nalwaysApply: true\n---
   • Rule content on line 4
3. Cursor automatically loads rules when repository is opened

Rationale: Project Rules allow better organization and easier maintenance of individual rules, while .cursorrules is simpler for single-file management.

---

Phase Documentation System

Overview

Phase documentation provides structured project management with four synchronized documents per phase:

• blueprint.md - Complete phase specification
• tasks.md - Task tracking (mirrors GitHub issues)
• decisions.md - Architecture Decision Records (ADRs)
• changelog.md - Change history

Directory Structure

pairs/phases/                    # or customize: project/phases/
├── phase-00-foundation/
│   ├── blueprint.md
│   ├── tasks.md
│   ├── decisions.md
│   └── changelog.md
├── phase-01-next-phase/
│   └── [same structure]
└── ...

Blueprint Template

File: pairs/phases/phase-XX-name/blueprint.md

Complete Template:

# Project Phase Document: Phase X - [Phase Name]

**Project:** [Project Name]  
**Phase:** Phase X: [Phase Name]  
**Project Manager:** [Name]  
**Technical Lead:** [Name]  
**Start Date:** YYYY-MM-DD  
**End Date:** YYYY-MM-DD  
**Version:** 1.0  
**Status:** ✅ Complete | 🔄 In Progress | ⏳ Planned

---

## 1. Phase Overview

### 1.1. Executive Summary
[2-3 paragraph summary of what this phase accomplishes and why it matters]

### 1.2. Phase Goals & Success Criteria

**Business Goals:**
- [Goal 1]
- [Goal 2]

**Technical Goals:**
- [Goal 1]
- [Goal 2]

**Success Metrics (KPIs):**
- ✅ [Metric 1]
- ✅ [Metric 2]

**Definition of Done:**
- [ ] [Criterion 1]
- [ ] [Criterion 2]

---

## 2. Scope & Deliverables

### 2.1. In-Scope Items
- [Item 1]
- [Item 2]

### 2.2. Out-of-Scope Items
- [Item 1]
- [Item 2]

### 2.3. Phase Deliverables
- [ ] [Deliverable 1]
- [ ] [Deliverable 2]

---

## 3. Technical Specifications

### 3.1. System Architecture
[Description of architecture for this phase]

### 3.2. Technology Stack
- **Programming Languages & Frameworks:** [List]
- **Database:** [Description]
- **Infrastructure & Hosting:** [Description]
- **APIs & Integrations:** [List]

### 3.3. Coding Standards & Best Practices
- [Standard 1]
- [Standard 2]

### 3.4. Data Models & Schemas
- [Schema description or reference]

---

## 4. Team & Resource Allocation

| **Role** | **Name** | **Responsibilities** |
| :--- | :--- | :--- |
| Project Owner | [Name] | [Responsibilities] |
| Technical Lead | [Name] | [Responsibilities] |

### 4.2. Resource Requirements
- [Requirement 1]
- [Requirement 2]

---

## 5. Timeline & Milestones

| **Milestone** | **Target Date** | **Status** |
| :--- | :--- | :--- |
| [Milestone 1] | YYYY-MM-DD | ✅ Completed |
| [Milestone 2] | YYYY-MM-DD | 🔄 In Progress |

---

## 6. Risk Management

| **Risk Description** | **Likelihood (1-5)** | **Impact (1-5)** | **Mitigation Strategy** | **Contingency Plan** |
| :--- | :--- | :--- | :--- | :--- |
| [Risk 1] | [1-5] | [1-5] | [Strategy] | [Plan] |

---

## 7. Communication & Reporting

### 7.1. Meeting Cadence
- **Daily:** [Frequency]
- **Phase Retrospective:** [When]

### 7.2. Reporting
- [Reporting method]

---

## 8. Quality Assurance & Testing

### 8.1. Testing Strategy
- ✅ [Test 1]
- ✅ [Test 2]

### 8.2. Test Environments
- **Development:** [Description]
- **Production:** [Description]

---

## 9. Opportunities for Improvement & Lessons Learned

### 9.1. Process Improvements
- [Improvement 1]
- [Improvement 2]

### 9.2. Technology & Tool Suggestions
- [Suggestion 1]
- [Suggestion 2]

### 9.3. Lessons Learned
- [Lesson 1]
- [Lesson 2]

---

## 10. Phase Sign-off

### 10.1. Approval Criteria
- [x] All deliverables completed
- [x] Documentation up to date
- [x] Ready for next phase

### 10.2. Approvers
- **Project Owner:** [Name]

### 10.3. Sign-off Date
**YYYY-MM-DD** — Phase complete and ready for next phase

---

**Next Phase:** [Phase X+1 - Next Phase Name](./../phase-XX-next/blueprint.md)

Tasks Template

File: pairs/phases/phase-XX-name/tasks.md

Complete Template:

# Phase X – Tasks (Mirror of GitHub Issues)

This document tracks all actionable items for **Phase X: [Phase Name]**, mirroring corresponding GitHub issues and providing a low-friction view for progress tracking.

---

## 🔧 [Category Name]

* [ ] **PX-001:** [Task description]

* [ ] **PX-002:** [Task description]

---

## 📜 [Category Name]

* [ ] **PX-003:** [Task description]

---

## ✅ Completion Criteria

To mark Phase X as complete:

* [ ] [Criterion 1]

* [ ] [Criterion 2]

---

**Linked Documents:**

* Blueprint: [Phase X – [Phase Name]](./blueprint.md)

---

*Use this list during daily and weekly reviews. Update checkboxes as tasks are completed or issues are closed in GitHub.*

Decisions Template

File: pairs/phases/phase-XX-name/decisions.md

Complete Template:

# Phase X – Architectural Decisions (ADRs)

## ADR-000: [Decision Title]

**Status:** Accepted | Proposed | Deprecated | Superseded  
**Date:** YYYY-MM-DD

**Context:** [What problem or need prompted this decision]

**Decision:** [What was decided]

**Consequences:**
- ✅ [Positive consequence]
- ⚠️ [Warning or trade-off]

---

## ADR-001: [Next Decision]

[Same format as above]

---

Changelog Template

File: pairs/phases/phase-XX-name/changelog.md

Complete Template:

# Phase X – Changelog

- **YYYY-MM-DD:** [Description of change]
- **YYYY-MM-DD:** [Description of change]
- **YYYY-MM-DD:** [Description of change]

Format Rules:

• One entry per line
• Date format: YYYY-MM-DD
• Use format: - **YYYY-MM-DD:** [Description]
• Most recent entries at top (optional, but recommended)

Synchronization Rules

When blueprint.md is modified:

1. Update changelog.md:

   • Add entry: - **YYYY-MM-DD:** [Description of blueprint changes]
   • Include: project name changes, milestone updates, scope changes, status changes

2. Sync tasks.md:

   • Align checkboxes with blueprint "Definition of Done" items
   • Align task list with blueprint "Phase Deliverables" section
   • Update phase status if blueprint status changed

3. Review decisions.md:

   • Add ADR if blueprint reflects new architectural decision
   • Verify existing ADRs still align with blueprint specifications

4. Verify consistency:

   • Project name matches across all documents
   • Dates are consistent
   • Status indicators are aligned

Rationale: Keeping documents synchronized ensures no information is lost and all documentation stays current. This is critical for LLM agents that rely on documentation accuracy.

---

Knowledge Base (KB) System

Overview

The KB system provides a lightweight, LLM-friendly staging area for external information that may inform project development. It uses structured routing, confidence scoring, and automatic indexing.

Directory Structure

kb/
├── 01_projects/              # Project-specific notes
│   ├── [project-name]/       # Current project notes
│   └── _shared/              # Cross-project notes
├── 02_systems/               # Infrastructure, DevOps, tooling
├── 03_research/              # Informal research, links
├── 04_design/                # Product specs, UX, copy
├── 05_decisions/              # ADR-style decisions
├── 06_glossary/               # Terms, acronyms
├── 07_playbooks/             # How-to guides, SOPs
├── 08_archive/               # Superseded content
├── _guides/                   # KB system guidelines (read-only)
│   └── KB_INGEST_PROMPT.md    # System prompt for ingestion
├── _templates/                # File templates (read-only)
│   ├── note.md
│   ├── decision.md
│   └── howto.md
├── _inbox/                    # Unclassified content (rare)
├── _review_queue/             # Low-confidence routing (<0.60)
├── _index.md                  # Auto-generated searchable index
├── CHANGELOG.md               # KB change tracking
├── README.md                  # KB system documentation
└── scripts/
    └── generate-index.sh      # Index generation script

File Naming Schema

Pattern: YYYY-MM-DD--slug--type.md

Components:

• Date (YYYY-MM-DD): Date content was created or captured
• Slug: 3-8 lowercase words, hyphen-joined, no stop-words (a, an, the, and, or, but, etc.)
• Type: One of: idea, note, spec, decision, howto, retro, meeting
• Multi-part files: Append --p1, --p2, etc. for long content

Examples:

• ✅ 2025-11-06--api-authentication-flow--spec.md
• ✅ 2025-11-06--user-onboarding-decision--decision.md
• ❌ api-design.md (missing date and type)
• ❌ 2025-11-06--the-api--note.md (contains stop-word "the")

Regex Pattern:

^\d{4}-\d{2}-\d{2}--[a-z0-9-]{3,}--(idea|note|spec|decision|howto|retro|meeting)(--p[0-9]+)?\.md$

Frontmatter Schema

18 Required Fields:

---
title: "Descriptive title in sentence case"
date: "YYYY-MM-DD"                    # Must match filename date
captured_at: "YYYY-MM-DD"             # Same as date (project compatibility)
author: ["author name"]                # Array, default ["unknown author"]
source: { kind: pulse|chat|web|doc, ref: "<link-or-id>" }
source_type: voice|web|pdf|image|personal_note|chat|pulse
project: ["project-name"]             # Array, customize for your project
related_projects: ["project-name"]     # Same as project (compatibility)
topics: ["topic1", "topic2"]          # Array of 2-5 topic keywords
tags: ["tag1", "tag2"]                # Array of 2-8 tags
type: idea|note|spec|decision|howto|retro|meeting  # Must match filename type
status: draft|active|archived
phase_relevance: ["phase-01", "phase-02"]  # Array of relevant phases or []
routing_hint: "Brief explanation of routing decision"
proposed_path: "kb/XX_category/"      # Where LLM intends to file it
routing_confidence: 0.87              # Numeric 0.00-1.00
related: []                           # Array of related file paths
summary: "One to three sentence summary of the content"
---

Optional Fields:

key_takeaways: ["takeaway1", "takeaway2"]
action_candidates: ["action1", "action2"]

Routing Decision Tree

1. Is it project-specific? → /kb/01_projects/[project]/ or _shared/
2. Is it a how-to or procedure? → /kb/07_playbooks/
3. Is it a decision with rationale? → /kb/05_decisions/
4. Is it about infrastructure/tooling? → /kb/02_systems/
5. Is it research or external reference? → /kb/03_research/
6. Is it design/UX/copy? → /kb/04_design/
7. Is it a definition or term? → /kb/06_glossary/
8. Is it obsolete? → /kb/08_archive/ (only if truly superseded)
9. Unclear? → /kb/_inbox/ (should be rare)

Routing Confidence System

Confidence Levels:

• 0.90–1.00: Crystal clear placement - content clearly matches category
• 0.75–0.89: Good guess - content fits well but might have minor ambiguity
• 0.60–0.74: Uncertain - content could fit multiple categories, needs review
• <0.60: Low confidence - unclear routing, send to _review_queue/ instead of proposed path

Policy: If routing_confidence < 0.60, the file MUST be placed in kb/_review_queue/ instead of the proposed path, but still include proposed_path in frontmatter for human review.

KB File Templates

Note Template

File: kb/_templates/note.md

---
title: "${TITLE}"
date: "${DATE}"
captured_at: "${DATE}"
author: ["${AUTHOR}"]
source: { kind: ${SRC_KIND}, ref: "${SRC_REF}" }
source_type: ${SOURCE_TYPE}
project: [${PROJECTS}]
related_projects: [${PROJECTS}]
topics: [${TOPICS}]
tags: [${TAGS}]
type: note
status: draft
phase_relevance: [${PHASE_RELEVANCE}]
routing_hint: "${ROUTING_HINT}"
proposed_path: "kb/XX_category/"
routing_confidence: 0.75
related: [${RELATED}]
summary: "${SUMMARY}"
key_takeaways: []
action_candidates: []
---

# Context

# Key Points

# Key Takeaways

# Action Candidates

# Actions / Next Steps

# References

Decision Template

File: kb/_templates/decision.md

---
title: "${TITLE}"
date: "${DATE}"
captured_at: "${DATE}"
author: ["${AUTHOR}"]
source: { kind: ${SRC_KIND}, ref: "${SRC_REF}" }
source_type: ${SOURCE_TYPE}
project: [${PROJECTS}]
related_projects: [${PROJECTS}]
topics: [${TOPICS}]
tags: [decision, ${TAGS}]
type: decision
status: active
phase_relevance: [${PHASE_RELEVANCE}]
routing_hint: "${ROUTING_HINT}"
proposed_path: "kb/05_decisions/"
routing_confidence: 0.90
related: [${RELATED}]
summary: "${SUMMARY}"
key_takeaways: []
action_candidates: []
---

## Decision

## Context

## Options Considered

## Rationale

## Consequences

## Key Takeaways

## Action Candidates

## Revisit Date

HowTo Template

File: kb/_templates/howto.md

---
title: "${TITLE}"
date: "${DATE}"
captured_at: "${DATE}"
author: ["${AUTHOR}"]
source: { kind: ${SRC_KIND}, ref: "${SRC_REF}" }
source_type: ${SOURCE_TYPE}
project: [${PROJECTS}]
related_projects: [${PROJECTS}]
topics: [${TOPICS}]
tags: [howto, ${TAGS}]
type: howto
status: active
phase_relevance: [${PHASE_RELEVANCE}]
routing_hint: "${ROUTING_HINT}"
proposed_path: "kb/07_playbooks/"
routing_confidence: 0.90
related: [${RELATED}]
summary: "${SUMMARY}"
key_takeaways: []
action_candidates: []
---

## Steps

1.

2.

3.

## Verification

## Rollback

## Key Takeaways

## Action Candidates

KB Ingestion Prompt

File: kb/_guides/KB_INGEST_PROMPT.md

Purpose: System prompt for LLM-assisted KB ingestion

Complete Content: [See full content in templates section below - this is a large file that should be copied exactly]

Index Generation

Script: kb/scripts/generate-index.sh

Purpose: Generates kb/_index.md with searchable metadata

Key Features:

• Scans all KB files
• Extracts frontmatter metadata
• Generates topics index, tags index, phase relevance index
• Updates automatically via GitHub Actions

Manual Execution:

kb/scripts/generate-index.sh

Auto-Update: GitHub Actions workflow (.github/workflows/kb-index-update.yml) runs on push to main when KB files change.

---

GitHub Automation System

Overview

The .github/ directory contains GitHub Actions workflows and documentation for repository automation. It follows a structured documentation pattern that keeps automation decisions and changes tracked.

Directory Structure

.github/
├── workflows/                    # GitHub Actions workflows
│   ├── daily-pulse.yml           # Example: Daily automation
│   ├── kb-lint.yml               # KB file validation
│   ├── kb-index-update.yml       # KB index auto-update
│   └── [other-workflows].yml
├── README.md                     # .github directory overview
├── CHANGELOG.md                  # Workflow change tracking
├── decisions.md                  # Automation decisions
└── LLM-Usage-Guide--{REPO}.md    # Per-repo LLM instructions

.github/README.md Template

# .github Directory

_Last updated: YYYY-MM-DD_

## Purpose

The `.github/` directory contains GitHub Actions workflows, issue templates, and documentation for repository automation and maintenance.

---

## Contents

### Workflows (`workflows/`)

GitHub Actions workflows that automate various aspects of the repository:

- **`[workflow-name].yml`** - [Description]

### Documentation

- **`README.md`** (this file) - Overview of .github directory structure and purpose
- **`CHANGELOG.md`** - Tracks all changes to workflows and .github folder
- **`decisions.md`** - Documents decisions about workflows, automation, and GitHub Actions
- **`LLM-Usage-Guide--{REPO-NAME}.md`** - LLM instructions for this repository's workflows and automation

---

## Workflow Overview

### [Workflow Name]
- **Schedule**: [When it runs]
- **Purpose**: [What it does]
- **Output**: [What it produces]

---

## Maintenance

### When Adding New Workflows

1. **Update `CHANGELOG.md`** - Document the new workflow and its purpose
2. **Update `decisions.md`** - Document why this workflow was added
3. **Update this README** - Add workflow to the overview section
4. **Update `LLM-Usage-Guide--{REPO-NAME}.md`** - Add instructions for the new workflow

### When Modifying Existing Workflows

1. **Update `CHANGELOG.md`** - Document what changed and why
2. **Update `decisions.md`** - Document the decision behind the change
3. **Test workflow** - Verify changes work as expected
4. **Update documentation** - Ensure README and LLM guide reflect changes

### When Removing Workflows

1. **Update `CHANGELOG.md`** - Document removal and reason
2. **Update `decisions.md`** - Document why workflow was removed
3. **Update this README** - Remove from overview
4. **Update `LLM-Usage-Guide--{REPO-NAME}.md`** - Remove references

---

**Location**: `.github/`  
**Maintained by**: [Your Name]

.github/CHANGELOG.md Template

# Changelog — .github Directory

All notable changes to workflows, automation, and .github folder structure.

## [YYYY-MM-DD] Brief Description

### Added
- **`[file-path]`** - [Description]

### Changed
- **`[file-path]`** - [Description of change]

### Fixed
- **`[file-path]`** - [Bug fix description]

### Notes
- [Additional context or important information]

---

## [Previous Date] Previous Change

[Same format as above]

---

.github/decisions.md Template

# Decisions — .github Directory

_Last updated: YYYY-MM-DD_

## Purpose

This document tracks decisions made about GitHub Actions workflows, automation, and the .github directory structure. Decisions are documented with context, rationale, and alternatives considered.

---

## Decision Format

Each decision entry includes:
- **Date**: When the decision was made
- **Context**: What problem or need prompted this decision
- **Decision**: What was decided
- **Rationale**: Why this approach was chosen
- **Alternatives**: Other options considered
- **Impact**: What this affects

---

## Decisions

### [YYYY-MM-DD] Decision Title

**Context**: [What prompted this decision]

**Decision**: [What was decided]

**Rationale**:
- [Reason 1]
- [Reason 2]

**Alternatives Considered**:
- [Alternative 1] - [Why not chosen]
- [Alternative 2] - [Why not chosen]

**Impact**:
- [Impact 1]
- [Impact 2]

---

## Future Decisions

Decisions about new workflows, automation changes, or .github structure modifications should be added here with the same format.

---

**Location**: `.github/decisions.md`  
**Maintained by**: [Your Name]

.github/LLM-Usage-Guide Template

File: .github/LLM-Usage-Guide--{REPO-NAME}.md

Naming Convention: Use LLM-Usage-Guide--{REPO-NAME}.md where {REPO-NAME} is your repository name. This enables automated sync scripts to identify target repos.

Template:

# LLM Usage Guide for GitHub Workflows — {REPO-NAME}

_Last updated: YYYY-MM-DD_

## Purpose

This guide provides instructions for AI assistants (LLMs) on how to work with GitHub Actions workflows, automation, and the `.github/` directory structure in this repository.

---

## Repository Context

**Repository**: `{repo-name}`  
**Primary System**: [System name]  
**Automation Focus**: [What this repo automates]

---

## Understanding .github Directory Structure

### Workflows (`workflows/`)

GitHub Actions workflows automate repository operations:

- **`[workflow-name].yml`** - [Description]

### Documentation

- **`README.md`** - Overview of .github directory and workflows
- **`CHANGELOG.md`** - Tracks all changes to workflows and .github folder
- **`decisions.md`** - Documents decisions about workflows and automation
- **`LLM-Usage-Guide--{REPO-NAME}.md`** (this file) - LLM instructions for this repo

---

## Working with Workflows

### When Modifying Workflows

**MANDATORY**: When any workflow file is modified:

1. **Update `.github/CHANGELOG.md`**:
   - Add entry with date and description
   - Document what changed and why
   - Include affected workflow name

2. **Update `.github/decisions.md`** (if decision-related):
   - Document the decision behind the change
   - Explain rationale and alternatives considered
   - Note impact on automation

3. **Update `.github/README.md`** (if structure changes):
   - Update workflow descriptions if behavior changed
   - Add new workflows to overview
   - Remove references to deleted workflows

4. **Test the workflow**:
   - Use `workflow_dispatch` trigger if available
   - Verify expected behavior
   - Check for errors in Actions tab

### When Adding New Workflows

1. Create workflow file in `.github/workflows/`
2. Update `.github/CHANGELOG.md` - Document new workflow
3. Update `.github/decisions.md` - Document why workflow was added
4. Update `.github/README.md` - Add to workflow overview
5. Test workflow - Verify it runs successfully
6. Update this guide - Add instructions if needed

---

## Workflow-Specific Instructions

### [Workflow Name]

**File**: `.github/workflows/[workflow-name].yml`

**Purpose**: [What it does]

**When to modify**:
- [Condition 1]
- [Condition 2]

**Validation**:
- [Check 1]
- [Check 2]

---

## Documentation Maintenance

### .github/CHANGELOG.md

**Purpose**: Track all changes to workflows and .github folder

**Format**:
```markdown
## [YYYY-MM-DD] Brief Description

### Added
- New workflow or feature

### Changed
- Modified workflow behavior

### Fixed
- Bug fix or correction

When to update: Every time a workflow file is modified

.github/decisions.md

Purpose: Document decisions about workflows and automation

Format:

### [YYYY-MM-DD] Decision Title

**Context**: What prompted this decision
**Decision**: What was decided
**Rationale**: Why this approach
**Alternatives**: Other options considered
**Impact**: What this affects

When to update: When making significant workflow decisions

---

Common Tasks

Adding a New Workflow

1. Create workflow file in .github/workflows/
2. Add workflow to .github/README.md overview
3. Document in .github/CHANGELOG.md
4. Document decision in .github/decisions.md (if applicable)
5. Test workflow with workflow_dispatch
6. Commit all changes together

Modifying an Existing Workflow

1. Make workflow changes
2. Update .github/CHANGELOG.md with change description
3. Update .github/decisions.md if decision-related
4. Update .github/README.md if behavior changed significantly
5. Test workflow
6. Commit changes

---

Validation Checklist

Before committing workflow changes:

• Workflow file syntax is valid YAML
• Workflow tested with workflow_dispatch (if available)
• .github/CHANGELOG.md updated with change description
• .github/decisions.md updated (if decision-related)
• .github/README.md updated (if structure/behavior changed)
• All changes committed together
• Commit message follows conventional format: ci(workflows): description

---

Repository: {repo-name}
Location: .github/LLM-Usage-Guide--{REPO-NAME}.md
Maintained by: [Your Name]

### Example Workflow: KB Lint

**File**: `.github/workflows/kb-lint.yml`

**Purpose**: Validates KB file naming, frontmatter, and structure

**Complete Workflow** (see validation section for full details):

```yaml
name: KB Lint

on:
  push:
    paths:
      - 'kb/**/*.md'
  pull_request:
    paths:
      - 'kb/**/*.md'

permissions:
  contents: read

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Validate KB Files
        run: |
          # Validation script (see Schemas and Validation section)

---

LLM Usage Guides

Overview

LLM Usage Guides are prompt documents that provide step-by-step instructions for AI assistants to perform specific tasks. They are designed for drag-and-drop use in Cursor chat.

Prompt Document Structure

Location: docs/PROMPTS/

Naming Convention: NN-Descriptive-Name-Prompt.md where NN is zero-padded two-digit number (00, 01, 02, etc.)

Example: 01-Project-Status-Check-Prompt.md

Prompt Document Template

# [Task Name] Prompt

**Purpose:** [One sentence describing what this prompt accomplishes]

**How to Use:** Drag this entire document into a Cursor chat session, then [provide context/information]. The AI assistant will follow these instructions to [accomplish the task].

---

## CRITICAL: Information Gathering

### Required Information (You should provide this)

Before starting, **ASK THE USER** for the following information if not already provided:

1. **[Information Item 1]** (REQUIRED)
   - Format/constraints
   - Examples
   - Why it's needed

2. **[Information Item 2]** (REQUIRED)
   - ...

### If Information is Missing

**ALWAYS ASK** for missing required information before proceeding. Do not make assumptions about:
- [List of things not to assume]

---

## Step-by-Step Process

### Phase 1: [Phase Name]

[Description of what this phase accomplishes]

1. **Step description:**
   ```bash
   # Commands or code

2. Validation:
   • How to verify this step succeeded
   • What to check

Phase 2: [Phase Name]

...

---

Error Handling

Common Issues

[Issue Name]

• Error message: What you'll see
• Fix: How to resolve it
• Prevention: How to avoid it

---

Validation Checklist

Before completing, verify:

• [Checklist item 1]
• [Checklist item 2]
• ...

---

Important Notes for AI Assistant

1. [Critical instruction 1]
2. [Critical instruction 2]
3. ...

### LLM Usage Guide for Prompts

**File**: `docs/PROMPTS/LLM-Usage-Guide.md`

**Purpose**: Instructions for LLMs on how to recognize, interpret, and execute prompt documents

**Key Sections**:
- Recognizing Prompt Documents
- Executing Prompts (Phase-by-Phase)
- Information Gathering
- Error Handling
- Validation Steps
- Providing Feedback

**Complete Template**: [See full content in templates section below]

### Prompt Creation Guide

**File**: `docs/PROMPTS/Prompt-Creation-Guide.md`

**Purpose**: Guide for creating effective, reusable prompt documents

**Key Sections**:
- Naming Convention
- Prompt Structure Template
- Best Practices
- Writing Effective Instructions
- Testing Your Prompt
- Common Patterns

**Complete Template**: [See full content in templates section below]

---

## Schemas and Validation

### KB File Validation Rules

**Filename Pattern**:

^\d{4}-\d{2}-\d{2}--[a-z0-9-]{3,}--(idea|note|spec|decision|howto|retro|meeting)(--p[0-9]+)?.md$

**Frontmatter Requirements**:
- Must have YAML frontmatter delimited by `---`
- All 18 required fields must be present
- Date in frontmatter must match filename date
- Type in frontmatter must match filename type
- `routing_confidence` must be numeric 0.00-1.00
- Files with `routing_confidence < 0.60` must be in `_review_queue/`

**Validation Script Logic** (for GitHub Actions):

```bash
# Validate filename pattern
if ! [[ "$filename" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}--[a-z0-9-]+--(idea|note|spec|decision|howto|retro|meeting)(--p[0-9]+)?\.md$ ]]; then
  echo "❌ ERROR: Invalid filename pattern"
  exit 1
fi

# Extract date and type from filename
filename_date=$(echo "$filename" | sed -E 's/^([0-9]{4}-[0-9]{2}-[0-9]{2})--.*/\1/')
filename_type=$(echo "$filename" | sed -E 's/.*--([a-z]+)(--p[0-9]+)?\.md$/\1/')

# Check frontmatter exists
if ! grep -q "^---$" "$file"; then
  echo "❌ ERROR: Missing frontmatter delimiter"
  exit 1
fi

# Extract frontmatter
frontmatter=$(sed -n '/^---$/,/^---$/p' "$file" | sed '1d;$d')

# Check required fields
REQUIRED_FIELDS=("title" "date" "author" "source" "project" "topics" "tags" "type" "status" "routing_hint" "proposed_path" "routing_confidence" "related" "summary")
for field in "${REQUIRED_FIELDS[@]}"; do
  if ! echo "$frontmatter" | grep -q "^${field}:"; then
    echo "❌ ERROR: Missing required field: $field"
    exit 1
  fi
done

# Validate date matches
frontmatter_date=$(echo "$frontmatter" | grep "^date:" | sed -E 's/^date:[[:space:]]*["'\'']?([^"'\'']+)["'\'']?.*/\1/' | tr -d ' ')
if [ "$frontmatter_date" != "$filename_date" ]; then
  echo "❌ ERROR: Date mismatch"
  exit 1
fi

# Validate type matches
frontmatter_type=$(echo "$frontmatter" | grep "^type:" | sed -E 's/^type:[[:space:]]*["'\'']?([^"'\'']+)["'\'']?.*/\1/' | tr -d ' ')
if [ "$frontmatter_type" != "$filename_type" ]; then
  echo "❌ ERROR: Type mismatch"
  exit 1
fi

# Validate routing_confidence
routing_confidence=$(echo "$frontmatter" | grep "^routing_confidence:" | sed -E 's/^routing_confidence:[[:space:]]*([0-9.]+).*/\1/' | tr -d ' ')
if ! awk -v conf="$routing_confidence" 'BEGIN {if (conf < 0.0 || conf > 1.0 || conf == "") exit 1}' 2>/dev/null; then
  echo "❌ ERROR: Invalid routing_confidence value"
  exit 1
fi

# Enforce review queue policy
if awk -v conf="$routing_confidence" 'BEGIN {exit !(conf < 0.60)}' 2>/dev/null; then
  if [[ "$file" != *"/_review_queue/"* ]]; then
    echo "❌ ERROR: File has routing_confidence < 0.60 but is not in kb/_review_queue/"
    exit 1
  fi
fi

Phase Blueprint Schema

Required Sections:

1. Phase Overview (Executive Summary, Goals, Success Criteria, Definition of Done)
2. Scope & Deliverables (In-Scope, Out-of-Scope, Deliverables)
3. Technical Specifications (Architecture, Technology Stack, Coding Standards, Data Models)
4. Team & Resource Allocation
5. Timeline & Milestones
6. Risk Management
7. Communication & Reporting
8. Quality Assurance & Testing
9. Opportunities for Improvement & Lessons Learned
10. Phase Sign-off

Status Values: ✅ Complete, 🔄 In Progress, ⏳ Planned

Date Format: YYYY-MM-DD

Research Note Schema

File Naming: YYYY-MM-DD-title.md

Frontmatter Requirements (project-specific, customize as needed):

---
title: "Title"
captured_at: "YYYY-MM-DD"
source_type: voice|web|pdf|image|personal_note|chat|pulse
tags: ["tag1", "tag2"]
phase_relevance: ["phase-01", "phase-02"]
---

---

File Structure and Conventions

Directory Naming

• Phase directories: phase-XX-name where XX is zero-padded number (00, 01, 02, etc.)
• KB categories: 01_projects/, 02_systems/, etc. (numbered for ordering)
• Special KB directories: _guides/, _templates/, _inbox/, _review_queue/ (underscore prefix)

File Naming Conventions

• Phase documentation: blueprint.md, tasks.md, decisions.md, changelog.md
• KB files: YYYY-MM-DD--slug--type.md
• Research notes: YYYY-MM-DD-title.md
• Scripts: kebab-case.sh or .py
• Workflows: kebab-case.yml

Markdown Formatting Standards

• Use consistent heading levels (## for main sections, ### for subsections)
• Include YAML front-matter for all structured documents
• Use tables for structured data (tasks, risks, milestones)
• Link between related documents using relative paths
• Use code fences with language tags for code blocks

Git Commit Messages

Format: type(scope): description

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• chore: Maintenance tasks
• ci: CI/CD changes

Examples:

• feat(phase-01): Add Zapier integration
• fix(phase-02): Resolve web link capture (#123)
• docs(kb): add api-auth-decision and update index/changelog
• ci(workflows): update kb-lint validation rules

---

Decision Rationale

Why Phase Documentation Synchronization is Mandatory

Problem: Documentation drifts apart over time, leading to inconsistencies and confusion.

Solution: Mandatory synchronization rules ensure related documents stay in sync automatically.

Benefits:

• No information loss
• Consistent project state
• LLM agents have accurate context
• Reduced manual maintenance

Trade-offs:

• Requires discipline to follow rules
• Initial setup overhead
• But: Prevents much larger problems later

Why KB System Exists Alongside Research System

Problem: Need different systems for different types of content.

Solution: Two complementary systems:

• KB system: Lightweight, informal, LLM-friendly staging area
• Research system: Formal, structured, full metadata schema

Benefits:

• Right tool for right content
• Clear separation of concerns
• KB can feed into research system
• Different validation rules for each

Rationale: Not all content needs full research treatment. KB provides quick capture, research provides deep analysis.

Why Routing Confidence System

Problem: LLM routing decisions aren't always perfect, need human review for uncertain cases.

Solution: Confidence scoring (0.00-1.00) with automatic routing to review queue for low confidence (<0.60).

Benefits:

• Catches routing mistakes early
• Allows human review of uncertain items
• Provides feedback loop for improving routing
• Prevents misclassified content from getting lost

Rationale: Better to flag uncertain items than silently misroute them.

Why Two-Phase Status Report Architecture

Problem: LLM-generated reports were incomplete (extraction issues) and expensive (full formatting).

Solution: Two-phase architecture:

• Phase 1: Script generates complete raw reports (reliable, complete)
• Phase 2: LLM adds only analytical sections (smaller, cheaper)

Benefits:

• 60-70% reduction in LLM token usage
• Complete reports every time (no extraction issues)
• Faster generation (smaller LLM calls)
• PMO-ready structured JSON
• Can review raw data before LLM processing

Rationale: Separation of data gathering (script) and analysis (LLM) provides better reliability and cost efficiency.

Why Cursor Rules System

Problem: Need consistent AI agent behavior across project.

Solution: Comprehensive .cursorrules file or Project Rules with mandatory synchronization and validation rules.

Benefits:

• Consistent agent behavior
• Automatic documentation synchronization
• Reduced manual oversight
• Better project maintenance

Rationale: AI agents need clear rules to follow. Well-structured rules prevent common mistakes and ensure quality.

---

Step-by-Step Replication Guide

Prerequisites

• GitHub repository (new or existing)
• Cursor IDE installed
• Git configured
• Basic understanding of Markdown and YAML

Phase 1: Create Directory Structure

1. Create main directories:

   mkdir -p .github/workflows
   mkdir -p docs/PROMPTS
   mkdir -p pairs/phases  # or customize: project/phases/
   mkdir -p kb/{01_projects,02_systems,03_research,04_design,05_decisions,06_glossary,07_playbooks,08_archive,_guides,_templates,_inbox,_review_queue,scripts}
   

2. Create phase directory structure:

   mkdir -p pairs/phases/phase-00-foundation
   # Repeat for each phase
   

3. Verify structure:

   tree -L 3  # or use ls -R
   

Phase 2: Set Up Cursor Rules

Option A: Single .cursorrules File

1. Create .cursorrules in project root
2. Copy complete .cursorrules content from "Cursor Rules System" section above
3. Customize project name and paths
4. Save file

Option B: Project Rules (.cursor/rules/*.mdc)

1. Create .cursor/rules/ directory
2. For each rule, create .mdc file with:
   • Frontmatter: ---\nalwaysApply: true\n---
   • Rule content
3. See "Cursor Rules System" section for individual rules

Phase 3: Create Phase Documentation Templates

1. Create first phase directory:

   mkdir -p pairs/phases/phase-00-foundation
   

2. Create blueprint.md:

   • Copy template from "Phase Documentation System" section
   • Customize for your project
   • Fill in Phase 0 details

3. Create tasks.md:

   • Copy template from "Phase Documentation System" section
   • Add initial tasks

4. Create decisions.md:

   • Copy template from "Phase Documentation System" section
   • Add initial ADRs if any

5. Create changelog.md:

   • Copy template from "Phase Documentation System" section
   • Add initial entry

Phase 4: Set Up KB System

1. Create KB directory structure (already done in Phase 1)

2. Create KB README.md:

   cp [template] kb/README.md
   # Or create from template in "KB System" section
   

3. Create KB templates:

   # Copy templates from "KB System" section
   # Create kb/_templates/note.md
   # Create kb/_templates/decision.md
   # Create kb/_templates/howto.md
   

4. Create KB ingestion prompt:

   # Copy KB_INGEST_PROMPT.md content from templates section
   # Create kb/_guides/KB_INGEST_PROMPT.md
   

5. Create index generation script:

   # Copy generate-index.sh from KB system section
   # Create kb/scripts/generate-index.sh
   chmod +x kb/scripts/generate-index.sh
   

6. Create KB CHANGELOG.md:

   # Create kb/CHANGELOG.md with initial entry
   

Phase 5: Configure GitHub Actions

1. Create .github/README.md:

   • Copy template from "GitHub Automation System" section
   • Customize for your workflows

2. Create .github/CHANGELOG.md:

   • Copy template from "GitHub Automation System" section
   • Add initial entry

3. Create .github/decisions.md:

   • Copy template from "GitHub Automation System" section

4. Create .github/LLM-Usage-Guide--{REPO-NAME}.md:

   • Copy template from "GitHub Automation System" section
   • Replace {REPO-NAME} with your repository name

5. Create workflows (examples):

   • .github/workflows/kb-lint.yml - KB validation
   • .github/workflows/kb-index-update.yml - KB index auto-update
   • Add other workflows as needed

Phase 6: Create LLM Usage Guides

1. Create docs/PROMPTS/ directory (already done in Phase 1)

2. Create LLM-Usage-Guide.md:

   • Copy template from "LLM Usage Guides" section
   • Customize for your project

3. Create Prompt-Creation-Guide.md:

   • Copy template from "LLM Usage Guides" section

4. Create initial prompt documents:

   • Use naming convention: NN-Descriptive-Name-Prompt.md
   • Start with 00- for first prompt

Phase 7: Validation and Testing

1. Test Cursor rules:

   • Open project in Cursor
   • Verify rules are loaded (check Cursor settings)
   • Test by editing a blueprint.md and verifying synchronization

2. Test KB system:

   • Create a test KB file
   • Run index generation: kb/scripts/generate-index.sh
   • Verify kb/_index.md is generated
   • Test KB lint workflow (if configured)

3. Test phase documentation:

   • Edit a blueprint.md
   • Verify changelog.md, tasks.md, decisions.md are checked/updated
   • Verify README.md is checked

4. Test GitHub Actions:

   • Push changes to trigger workflows
   • Verify workflows run successfully
   • Check that documentation is updated

Phase 8: Customization

1. Customize project name:

   • Replace "PAIRS" or placeholder names throughout
   • Update all references in documentation

2. Customize directory names:

   • If not using "pairs/", update all references
   • Update Cursor rules paths

3. Customize phase structure:

   • Adjust phase numbering if needed
   • Customize phase names

4. Customize KB categories:

   • Adjust category names if needed
   • Update routing decision tree

5. Add project-specific rules:

   • Add to .cursorrules or Project Rules
   • Document in appropriate guides

---

Templates

Complete KB Ingestion Prompt

File: kb/_guides/KB_INGEST_PROMPT.md

Complete Content (copy this exactly):

# KB Ingestion System Prompt

**Use this prompt in Cursor before pasting content to be ingested into the Knowledge Base.**

---

## System Instructions

You are a Knowledge Base ingestion assistant. Your role is to analyze incoming content (from "Pulse Daily" chats, ideas, notes, etc.) and route it to the appropriate location in the `/kb/` directory structure with proper naming, frontmatter, and formatting.

## Classification and Routing Rules

Content must be routed to one of these directories based on its primary purpose:

- **`/kb/01_projects/[project-name]/`** - Project-specific notes, tasks, or updates
- **`/kb/01_projects/_shared/`** - Cross-project notes that apply to multiple projects
- **`/kb/02_systems/`** - Infrastructure, DevOps, tooling, technical systems, architecture decisions
- **`/kb/03_research/`** - Links, papers, competitor notes, external research, learning materials
- **`/kb/04_design/`** - Product specs, UX design, copy, user experience, interface design
- **`/kb/05_decisions/`** - ADR-style decisions with rationale, architectural decisions, strategic choices
- **`/kb/06_glossary/`** - Terms, acronyms, definitions, vocabulary
- **`/kb/07_playbooks/`** - How-to guides, SOPs, runbooks, procedures, operational guides
- **`/kb/08_archive/`** - Old or superseded content (use sparingly, prefer deletion if truly obsolete)
- **`/kb/_inbox/`** - Use only if content cannot be clearly classified (should be rare)
- **`/kb/_review_queue/`** - Low-confidence routing items requiring human review (routing_confidence < 0.60)

### Routing Decision Tree

1. **Is it project-specific?** → `/kb/01_projects/[project]/` or `_shared/`
2. **Is it a how-to or procedure?** → `/kb/07_playbooks/`
3. **Is it a decision with rationale?** → `/kb/05_decisions/`
4. **Is it about infrastructure/tooling?** → `/kb/02_systems/`
5. **Is it research or external reference?** → `/kb/03_research/`
6. **Is it design/UX/copy?** → `/kb/04_design/`
7. **Is it a definition or term?** → `/kb/06_glossary/`
8. **Is it obsolete?** → `/kb/08_archive/` (only if truly superseded)
9. **Unclear?** → `/kb/_inbox/` (should be rare)

### Routing Confidence Assessment

After determining the proposed routing destination, you MUST assess your confidence level:

- **0.90–1.00:** Crystal clear placement - content clearly matches category, type, and purpose
- **0.75–0.89:** Good guess - content fits well but might have minor ambiguity
- **0.60–0.74:** Uncertain - content could fit multiple categories, needs review
- **<0.60:** Low confidence - unclear routing, send to `_review_queue/` instead of proposed path

**Routing Policy:** If `routing_confidence < 0.60`, the file MUST be placed in `kb/_review_queue/` instead of the proposed path, but still include `proposed_path` in frontmatter for human review.

## File Naming Standards

**Format:** `YYYY-MM-DD--slug--type.md`

### Components

- **Date (YYYY-MM-DD):** Use the date the content was created or captured (today's date if unknown)
- **Slug:** 3-8 lowercase words, hyphen-joined, no stop-words (a, an, the, and, or, but, etc.)
  - Good: `user-authentication-flow`, `api-rate-limiting-strategy`, `cursor-workflow-setup`
  - Bad: `the-api`, `a-user`, `and-authentication`
- **Type:** One of: `idea`, `note`, `spec`, `decision`, `howto`, `retro`, `meeting`
- **Multi-part files:** If content is too long, append `--p1`, `--p2`, etc. to the filename
  - Example: `2025-11-06--comprehensive-api-design--spec--p1.md`

### Type Selection

- **`idea`** - New concepts, proposals, brainstorming
- **`note`** - General notes, observations, thoughts
- **`spec`** - Specifications, requirements, detailed plans
- **`decision`** - ADR-style decisions (should go in `/kb/05_decisions/`)
- **`howto`** - Step-by-step guides (should go in `/kb/07_playbooks/`)
- **`retro`** - Retrospectives, post-mortems, lessons learned
- **`meeting`** - Meeting notes, summaries

## Frontmatter Requirements

Every KB file MUST have complete YAML frontmatter with all required fields. The base system requires 14 fields, but projects may add additional fields (like `captured_at`, `source_type`, `related_projects`, `phase_relevance` for PAIRS).

**Base Required Fields (14):**
```yaml
---
title: "Descriptive title in sentence case"
date: "YYYY-MM-DD"
author: ["author name"]  # Array, default to ["unknown author"] if unknown
source: { kind: pulse|chat|web|doc, ref: "<link-or-id>" }
project: ["project-name"]  # Array, customize for your project
topics: []  # Array of topic keywords
tags: []  # Array of tags for categorization
type: idea|note|spec|decision|howto|retro|meeting
status: draft|active|archived
routing_hint: "Brief explanation of why this was routed here"
proposed_path: "kb/XX_category/"  # Where LLM intends to file it
routing_confidence: 0.87  # Numeric value 0.00-1.00
related: []  # Array of related file paths or references
summary: "One to three sentence summary of the content"
---

Optional Project-Specific Fields (add as needed):

• captured_at - Same as date (for compatibility)
• source_type - voice|web|pdf|image|personal_note|chat|pulse
• related_projects - Same as project (for compatibility)
• phase_relevance - Array of relevant phases (e.g., ["phase-01", "phase-02"])
• key_takeaways - Array of key insights
• action_candidates - Array of potential action items

Field Guidelines

• title: Clear, descriptive, sentence case (not title case)
• date: Must match filename date prefix (YYYY-MM-DD)
• author: Array format, use ["unknown author"] if unknown
• source: Object with kind (pulse, chat, web, doc) and ref (link, ID, or identifier)
• project: Array, customize for your project, expandable for future projects
• topics: Array of 2-5 topic keywords (e.g., ["authentication", "security", "api"])
• tags: Array of 2-8 tags for cross-cutting categorization (e.g., ["backend", "urgent", "review-needed"])
• type: Must match filename type suffix exactly
• status: draft for new content, active for current/relevant, archived for old
• routing_hint: Brief explanation (1-2 sentences) of routing decision
• proposed_path: The directory path where the LLM intends to file the content
• routing_confidence: Numeric value between 0.00 and 1.00 indicating confidence in the routing decision
• related: Array of related file paths or references
• summary: Concise 1-3 sentence summary of the content

Output Format

CRITICAL: You MUST output your response in a JSON code block with this exact structure:

{
  "file_path": "kb/XX_category/YYYY-MM-DD--slug--type.md",
  "frontmatter": {
    "title": "...",
    "date": "YYYY-MM-DD",
    "author": ["..."],
    "source": { "kind": "...", "ref": "..." },
    "project": ["..."],
    "topics": ["..."],
    "tags": ["..."],
    "type": "...",
    "status": "...",
    "routing_hint": "...",
    "proposed_path": "kb/XX_category/",
    "routing_confidence": 0.87,
    "related": [],
    "summary": "..."
  },
  "content": "# Title\n\n[Markdown content here]"
}

IMPORTANT: The file_path in the JSON output MUST reflect the actual destination:

• If routing_confidence >= 0.60: Use the proposed_path as the actual file_path
• If routing_confidence < 0.60: Use kb/_review_queue/ as the actual file_path (but still include proposed_path in frontmatter)

Quality and Style Guidelines

1. Content Quality:

   • Preserve original meaning and intent
   • Improve clarity and structure without changing substance
   • Use proper Markdown formatting (headers, lists, code blocks)
   • Break long content into logical sections

2. Writing Style:

   • Use clear, concise language
   • Prefer active voice
   • Use proper grammar and spelling
   • Maintain professional tone

3. Structure:

   • Start with a clear title (H1)
   • Use H2 for major sections
   • Use H3 for subsections
   • Include a summary section if helpful
   • Add "Related" section for cross-references

4. Markdown Best Practices:

   • Use fenced code blocks with language tags
   • Use proper list formatting
   • Use links for references
   • Use emphasis (bold/italic) sparingly

Safety Constraints

NEVER:

• Modify files in /kb/_guides/ or /kb/_templates/
• Overwrite existing files without explicit user permission
• Create files outside /kb/ directory structure
• Skip frontmatter validation
• Use invalid filename patterns
• Create duplicate files (check existing files first)

ALWAYS:

• Validate filename matches pattern: YYYY-MM-DD--slug--type.md
• Ensure all required frontmatter fields are present
• Verify date in frontmatter matches filename date
• Verify type in frontmatter matches filename type
• Check for existing similar files to avoid duplicates
• Use appropriate routing based on content purpose
• Assess routing confidence honestly (0.00-1.00)
• Route low-confidence items (<0.60) to kb/_review_queue/ instead of proposed path

Example Workflow

1. User pastes content into Cursor
2. You analyze the content to determine:
   • Primary purpose and routing destination
   • Appropriate type (idea, note, spec, etc.)
   • Key topics and tags
   • Related content
   • Routing confidence level (0.00-1.00)
3. You generate:
   • Proper filename following naming standards
   • Complete frontmatter with all required fields
   • Well-structured Markdown content
4. You determine actual file path:
   • If routing_confidence >= 0.60: Use proposed_path as actual destination
   • If routing_confidence < 0.60: Use kb/_review_queue/ as actual destination
5. You output JSON code block with file_path, frontmatter, and content
6. User (or automation) creates the file from your JSON output

Validation Checklist

Before outputting JSON, verify:

• Filename matches pattern: YYYY-MM-DD--slug--type.md
• All required frontmatter fields are present
• Date in frontmatter matches filename date
• Type in frontmatter matches filename type
• Routing confidence is assessed honestly (0.00-1.00)
• proposed_path is set to intended destination directory
• Actual file_path reflects routing policy (if confidence < 0.60, use kb/_review_queue/)
• Routing destination is appropriate for content
• Content is well-structured Markdown
• Summary accurately describes the content
• Topics and tags are relevant and useful
• Related references are valid (if any)

---

Completion Summary and Reporting

CRITICAL: After outputting the JSON code block, you MUST also provide a completion summary in markdown format with the following sections:

What Was Accomplished

• File Created: kb/XX_category/YYYY-MM-DD--slug--type.md
• Routing Decision: [Brief explanation of why this content was routed to this category]
• Content Type: [type] in [category]
• File Status: [draft/active/archived]

KB File Details

• Title: [title from frontmatter]
• Type: [type from frontmatter]
• Topics: [list of topics from frontmatter]
• Tags: [list of tags from frontmatter]
• Summary: [summary from frontmatter]
• Author: [author from frontmatter]
• Source: [source kind and ref from frontmatter]

Possible Uses in Project

• [How this KB can be used in project planning/development]
• [Related workflows or decisions this informs]
• [Potential integrations with other systems or documentation]
• [Who might benefit from this knowledge]

Local Document Update Report

MANDATORY STEPS: After creating the KB file, you must:

1. Update Index:

   • Run: kb/scripts/generate-index.sh
   • This regenerates kb/_index.md with the new file's metadata
   • Verify the script completes successfully
   • Check that the new file appears in kb/_index.md

2. Update Changelog:

   • Add entry to kb/CHANGELOG.md with the following format:

     ## [YYYY-MM-DD] KB File Added
     
     ### Added
     - `kb/XX_category/YYYY-MM-DD--slug--type.md` - [Brief description of content]
     

   • Use today's date (YYYY-MM-DD format)
   • Include the full file path relative to repository root
   • Provide a brief description (1-2 sentences) of what the KB file contains

3. Commit Changes:

   • Commit all three changes together:
     • The new KB file
     • The updated kb/_index.md
     • The updated kb/CHANGELOG.md
   • Use commit message: docs(kb): add [filename-slug] and update index/changelog
   • Example: docs(kb): add api-auth-decision and update index/changelog

Status Checklist:

• KB file created at correct path
• Index updated: kb/scripts/generate-index.sh run successfully
• Changelog updated: Entry added to kb/CHANGELOG.md
• All changes committed together
• Commit message follows format: docs(kb): add [filename-slug] and update index/changelog

Note: If you cannot run the index generation script or update the changelog automatically, clearly indicate what needs to be done manually in the "Local Document Update Report" section.

---

Remember: The goal is to create well-organized, discoverable knowledge that can be easily found and referenced later. Take time to classify correctly and provide complete metadata. Always update the index and changelog after creating KB files.

**Note**: Customize the project name references (`[project-name]`) and add any project-specific frontmatter fields as needed for your project.

### Complete LLM Usage Guide for Prompts

**File**: `docs/PROMPTS/LLM-Usage-Guide.md`

**Purpose**: Instructions for LLMs on how to recognize, interpret, and execute prompt documents

**Key Sections** (copy complete content from original `docs/PROMPTS/LLM-Usage-Guide.md` file):
- Recognizing Prompt Documents
- Executing Prompts (Phase-by-Phase Execution)
- Information Gathering
- Error Handling
- Validation Steps
- Providing Feedback
- Best Practices
- Special Instructions
- Troubleshooting

**Note**: The complete file is quite extensive. Copy the entire content from the original `docs/PROMPTS/LLM-Usage-Guide.md` file in the PAIRS project, or use the template structure shown in the "LLM Usage Guides" section above as a starting point.

### Complete Prompt Creation Guide

**File**: `docs/PROMPTS/Prompt-Creation-Guide.md`

**Purpose**: Guide for creating effective, reusable prompt documents

**Key Sections** (copy complete content from original `docs/PROMPTS/Prompt-Creation-Guide.md` file):
- Naming Convention
- Prompt Structure Template
- Best Practices
- Writing Effective Instructions
- Testing Your Prompt
- Common Patterns
- When to Create a New Prompt
- Updating Existing Prompts
- Checklist for New Prompts

**Note**: The complete file is quite extensive. Copy the entire content from the original `docs/PROMPTS/Prompt-Creation-Guide.md` file in the PAIRS project, or use the template structure shown in the "LLM Usage Guides" section above as a starting point.

---

## Troubleshooting

### Cursor Rules Not Applying

**Symptoms**: AI agent doesn't follow rules, documentation not synchronized

**Solutions**:
1. Verify `.cursorrules` file exists in project root
2. Check Cursor settings → Rules, Memories, Commands → Project Rules
3. If using Project Rules, verify `.cursor/rules/*.mdc` files have correct frontmatter
4. Restart Cursor
5. Check file paths in rules match your directory structure

### KB Validation Failures

**Symptoms**: GitHub Actions KB lint workflow fails

**Solutions**:
1. Check filename matches pattern: `YYYY-MM-DD--slug--type.md`
2. Verify all 18 required frontmatter fields are present
3. Check date in frontmatter matches filename date
4. Check type in frontmatter matches filename type
5. Verify `routing_confidence` is numeric 0.00-1.00
6. If confidence < 0.60, verify file is in `_review_queue/`

### Phase Documentation Out of Sync

**Symptoms**: Blueprint, tasks, decisions, changelog don't match

**Solutions**:
1. Manually review all four documents
2. Update changelog.md with current date and description of discrepancies
3. Sync tasks.md with blueprint.md "Definition of Done" and "Phase Deliverables"
4. Review decisions.md for missing ADRs mentioned in blueprint
5. Verify project name matches across all documents
6. Check status indicators are aligned

### KB Index Not Updating

**Symptoms**: `kb/_index.md` doesn't reflect new KB files

**Solutions**:
1. Run index generation manually: `kb/scripts/generate-index.sh`
2. Check script has execute permissions: `chmod +x kb/scripts/generate-index.sh`
3. Verify GitHub Actions workflow is configured and running
4. Check workflow logs for errors
5. Verify KB files have valid frontmatter (index script requires it)

### GitHub Actions Workflow Failures

**Symptoms**: Workflows fail to run or produce errors

**Solutions**:
1. Check workflow YAML syntax is valid
2. Verify workflow triggers are correct (paths, events)
3. Check required secrets are configured
4. Review workflow logs for specific error messages
5. Test workflow with `workflow_dispatch` trigger
6. Verify file paths in workflow match actual structure

### LLM Prompt Not Executing Correctly

**Symptoms**: AI assistant doesn't follow prompt instructions

**Solutions**:
1. Verify prompt document is complete (all sections present)
2. Check prompt follows template structure
3. Ensure "CRITICAL" and "MANDATORY" sections are clearly marked
4. Verify information gathering section requests all required data
5. Test prompt with a simple task first
6. Review LLM-Usage-Guide.md for execution guidelines

---

## Conclusion

This guide provides everything needed to replicate the PAIRS documentation and automation system in another project. Key takeaways:

1. **Start with structure** - Create directories first
2. **Set up rules early** - Cursor rules ensure consistency
3. **Use templates** - All templates are provided above
4. **Validate frequently** - Automated validation catches issues early
5. **Document decisions** - ADRs and changelogs track evolution
6. **Keep synchronized** - Mandatory sync rules prevent drift

**Next Steps**:
1. Review this guide completely
2. Follow Step-by-Step Replication Guide
3. Customize for your project
4. Test each component
5. Iterate and improve

**Questions or Issues?**
- Review Troubleshooting section
- Check original PAIRS project for examples
- Refer to specific sections above for detailed information

---

**Document Version**: 1.0  
**Last Updated**: 2025-01-27  
**Maintained by**: [Your Name]  
**Based on**: PAIRS-for-the-Individual project documentation system