zhongwei/gh-levnikolaevich-claude-code-skills-full-development-workflow-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:37:27 +08:00
commit 37774aa937
131 changed files with 31137 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

475
skills/ln-110-documents-pipeline/SKILL.md Normal file
View File

@@ -0,0 +1,475 @@
---
name: ln-110-documents-pipeline
description: Orchestrates complete doc system via 6 workers (ln-111→ln-116). Each worker self-validates. Phase 4: global cleanup. Idempotent.
---
# Documentation Pipeline (Orchestrator)
This skill orchestrates the creation of a complete documentation system by invoking 6 specialized documentation workers in sequence. Each worker handles one domain (root/reference/tasks/project/presentation/test) and validates its own output, eliminating Worker→Worker coupling.
## When to Use This Skill
This skill should be used when:
- Start a new IT project and need complete documentation system at once
- Use automated workflow instead of manually invoking 6 workers
- Create entire documentation structure (CLAUDE.md → docs/ → presentation/) in one go
- Prefer orchestrated CREATE path over manual skill chaining
- Need automatic global cleanup (deduplication, orphaned files, consolidation)
**Alternative**: If you prefer granular control, invoke workers manually:
1. [ln-111-root-docs-creator](../ln-111-root-docs-creator/SKILL.md) - CLAUDE.md + docs/README.md + documentation_standards.md + principles.md
2. [ln-112-reference-docs-creator](../ln-112-reference-docs-creator/SKILL.md) - reference/ structure
3. [ln-113-tasks-docs-creator](../ln-113-tasks-docs-creator/SKILL.md) - tasks/README.md + kanban
4. [ln-114-project-docs-creator](../ln-114-project-docs-creator/SKILL.md) - project docs
5. [ln-115-presentation-creator](../ln-115-presentation-creator/SKILL.md) - HTML presentation
6. [ln-116-test-docs-creator](../ln-116-test-docs-creator/SKILL.md) - tests/README.md (optional)
**Note**: Each worker now validates its own output in Phase 2/3. Orchestrator handles global operations only.
## How It Works
The skill follows a 5-phase orchestration workflow: User confirmation → Invoke 6 workers sequentially → Global cleanup → Summary. Phase 3 (validation) is intentionally skipped - each worker validates its own output.
### Phase 1: User Confirmation
**Objective**: Check existing files, explain workflow, and get user approval.
**Process**:
1. **Pre-flight Check** (scan existing documentation):
- Use Glob tool to check all potential files:
- **Root docs** (4 files): `CLAUDE.md`, `docs/README.md`, `docs/documentation_standards.md`, `docs/principles.md`
- **Reference structure** (4 items): `docs/reference/README.md`, `docs/reference/adrs/`, `docs/reference/guides/`, `docs/reference/manuals/`
- **Tasks docs** (2 files): `docs/tasks/README.md`, `docs/tasks/kanban_board.md`
- **Project docs** (up to 7 files): `docs/project/requirements.md`, `architecture.md`, `tech_stack.md`, `api_spec.md`, `database_schema.md`, `design_guidelines.md`, `runbook.md`
- **Presentation** (3 items): `docs/presentation/README.md`, `presentation_final.html`, `assets/` directory
- **Test docs** (2 files): `docs/reference/guides/testing-strategy.md`, `tests/README.md`
- Count existing vs missing files
- Show user summary:
```
📊 Documentation Status:
✓ Found: X existing files
✗ Missing: Y files
⚠️ Pipeline will create ONLY missing files.
✅ Existing files will be preserved (no overwrites).
```
2. Show user what will be created:
- Root documentation (CLAUDE.md + docs/README.md + documentation_standards.md + principles.md via ln-111-root-docs-creator)
- Reference structure (docs/reference/ via ln-112-reference-docs-creator)
- Task management docs (docs/tasks/ via ln-113-tasks-docs-creator)
- Project documentation (docs/project/ via ln-114-project-docs-creator)
- HTML presentation (docs/presentation/ via ln-115-presentation-creator)
- Test documentation (tests/ via ln-116-test-docs-creator - optional)
- Estimated time: 15-20 minutes with interactive dialog
3. Ask: "Proceed with creating missing files? (yes/no)"
4. Ask: "Include test documentation (tests/README.md)? (yes/no)"
**Output**: File scan summary + user approval + test docs preference
---
### Phase 2: Invoke Workers Sequentially
**Objective**: Create complete documentation system by invoking 6 workers in order.
**Process** (AUTOMATIC invocations with Skill tool):
**2.1 Create Root Documentation**:
- **Invocation**: `Skill(skill: "ln-111-root-docs-creator")` → AUTOMATIC
- **Output**: `CLAUDE.md` + `docs/README.md` (root hub with general standards) + `docs/documentation_standards.md` (60 universal requirements) + `docs/principles.md` (11 development principles)
- **Validation**: ln-111 validates output in Phase 2/3 (SCOPE tags, Maintenance sections)
- **Verify**: All four files exist before continuing
**2.2 Create Reference Structure**:
- **Invocation**: `Skill(skill: "ln-112-reference-docs-creator")` → AUTOMATIC
- **Output**: `docs/reference/README.md` + `adrs/`, `guides/`, `manuals/` directories + ADR template
- **Validation**: ln-112 validates output in Phase 2/3
- **Verify**: Reference hub exists before continuing
**2.3 Create Task Management Docs**:
- **Invocation**: `Skill(skill: "ln-113-tasks-docs-creator")` → AUTOMATIC
- **Output**: `docs/tasks/README.md` + optionally `kanban_board.md` (if user provides Linear config)
- **Validation**: ln-113 validates output in Phase 2/3
- **Verify**: Tasks README exists before continuing
**2.4 Create Project Documentation**:
- **Invocation**: `Skill(skill: "ln-114-project-docs-creator")` → AUTOMATIC (requires user interaction for 23 technical questions)
- **Output**: `docs/project/requirements.md`, `architecture.md`, `tech_stack.md` + conditional: `api_spec.md`, `database_schema.md`, `design_guidelines.md`, `runbook.md` (3-7 documents based on project type)
- **Validation**: ln-114 validates output in Phase 2/3
- **Verify**: All required project docs exist before continuing
**2.5 Create HTML Presentation**:
- **Invocation**: `Skill(skill: "ln-115-presentation-creator")` → AUTOMATIC
- **Output**: `docs/presentation/README.md` + `presentation_final.html` + `assets/`
- **Validation**: ln-115 validates output in Phase 2/3
- **Verify**: Presentation files exist before continuing
**2.6 Create Test Documentation (Optional)**:
- **Condition**: If user approved test docs in Phase 1
- **Invocation**: `Skill(skill: "ln-116-test-docs-creator")` → AUTOMATIC
- **Output**: `tests/README.md` (test documentation with Story-Level Test Task Pattern)
- **Validation**: ln-116 validates output in Phase 2/3
- **Skip**: If "no" → can run ln-116-test-docs-creator later manually
**Output**: Complete documentation system with all 6 workers completed and validated
---
### Phase 4: Global Cleanup and Consolidation
**Objective**: Remove duplicates, orphaned files, consolidate knowledge across ALL documentation.
**Trigger**: Only after ALL workers complete Phase 2/3 validation.
**Process**:
**4.1 Scan for duplicate content**
1. **Read all .md files in docs/**
- Use Glob tool: `pattern: "docs/**/*.md"`
- Store list of all documentation files
2. **Identify duplicate sections:**
- For each file:
- Read file content
- Extract section headers (##, ###)
- Extract section content (text between headers)
- Compare sections across files:
- If 2+ sections have:
- Same heading (case-insensitive)
- >80% content similarity (simple word overlap check)
- Mark as duplicate
3. **Determine canonical version:**
- Rules for canonical location:
- "Development Principles" → principles.md (always canonical)
- "Testing Strategy" → testing-strategy.md (always canonical)
- "Linear Configuration" → tasks/kanban_board.md (always canonical)
- For other duplicates: Keep in FIRST file encountered (alphabetical order)
4. **Remove duplicates:**
- For each duplicate section:
- Use Edit tool to delete from non-canonical files
- Use Edit tool to add link to canonical location:
```markdown
See [Development Principles](../principles.md#development-principles) for details.
```
- Track count of removed duplicates
5. **Log results:**
- "✓ Removed {count} duplicate sections"
- List: "{section_name} removed from {file} (canonical: {canonical_file})"
**4.2 Scan for orphaned files**
1. **List all .md files in docs/**
- Use Glob tool: `pattern: "docs/**/*.md"`
2. **Check against expected structure:**
- Expected files (created by workers):
- docs/CLAUDE.md
- docs/README.md
- docs/documentation_standards.md
- docs/principles.md
- docs/project/requirements.md
- docs/project/architecture.md
- docs/project/tech_stack.md
- docs/project/api_spec.md (conditional)
- docs/project/database_schema.md (conditional)
- docs/project/design_guidelines.md (conditional)
- docs/project/runbook.md (conditional)
- docs/reference/README.md
- docs/reference/adrs/*.md (user-created)
- docs/reference/guides/*.md (user-created)
- docs/reference/manuals/*.md (user-created)
- docs/tasks/README.md
- docs/tasks/kanban_board.md
- docs/testing-strategy.md
- tests/README.md
- Any file NOT in this list = orphaned
3. **Move orphaned files to archive:**
- Create `.archive/YYYY-MM-DD/` directory (current date)
- For each orphaned file:
- Use Bash tool: `mv {file_path} .archive/YYYY-MM-DD/`
- Log: "Archived {file_name} (not in expected structure)"
- Track count
4. **Log results:**
- "✓ Archived {count} orphaned files to .archive/{date}/"
- List archived files
**4.3 Consolidate knowledge**
1. **Identify scattered information:**
- Known patterns:
- Linear config scattered: kanban_board.md + tasks/README.md
- Development principles scattered: principles.md + architecture.md + CLAUDE.md
- Testing info scattered: testing-strategy.md + tests/README.md + architecture.md
2. **For each scattered concept:**
- Determine Single Source of Truth (SSoT):
- Linear config → kanban_board.md
- Development principles → principles.md
- Testing strategy → testing-strategy.md
3. **Update non-SSoT files:**
- Use Edit tool to replace duplicate content with link:
```markdown
See [Linear Configuration](../tasks/kanban_board.md#linear-configuration) for team ID and settings.
```
- Track consolidation count
4. **Log results:**
- "✓ Consolidated {count} scattered concepts"
- List: "{concept} consolidated to {SSoT_file}"
**4.4 Cross-link validation**
1. **Scan all .md files for internal links:**
- For each file:
- Read content
- Extract all markdown links: `[text](path)`
- Filter internal links (relative paths, not http://)
2. **Verify link targets exist:**
- For each link:
- Resolve relative path
- Check if target file exists (Glob tool)
- If missing: Mark as broken
3. **Fix broken links:**
- For each broken link:
- If target was archived: Update link to archive path
- If target never existed: Remove link (convert to plain text)
- Track fix count
4. **Add missing critical links:**
- **CLAUDE.md → docs/README.md:**
- Read CLAUDE.md
- Check for link to docs/README.md
- If missing: Add in "Documentation Hub" section
- **docs/README.md → section READMEs:**
- Check for links to project/, reference/, tasks/, tests/ READMEs
- If missing: Add
- Track added links count
5. **Log results:**
- "✓ Fixed {count} broken links"
- "✓ Added {count} missing critical links"
- List changes
**4.5 Final report**
```
✅ Global Cleanup Complete:
Structure:
- Removed {N} duplicate sections (canonical: principles.md)
- Archived {N} orphaned files to .archive/YYYY-MM-DD/
- list of archived files
- Consolidated {N} scattered concepts
Links:
- Fixed {N} broken links
- Added {N} missing critical links:
- list of added links
```
**Output**: All documentation cleaned up, duplicates removed, orphaned files archived, knowledge consolidated, cross-links validated
---
### Phase 5: Summary and Next Steps
**Objective**: Provide complete overview of created system.
**Process**:
1. List all created files with sizes:
- `CLAUDE.md` (project entry point)
- `docs/README.md` (root documentation hub)
- `docs/documentation_standards.md` (60 universal requirements)
- `docs/principles.md` (11 development principles)
- `docs/project/requirements.md`, `architecture.md`, `tech_stack.md` + conditional documents (3-7 total)
- `docs/reference/README.md` (reference hub with empty adrs/, guides/, manuals/ directories)
- `docs/tasks/README.md` + optionally `kanban_board.md`
- `docs/presentation/README.md` + `presentation_final.html`
- `tests/README.md` (if created)
2. Show documentation system features:
- ✅ SCOPE tags (document boundaries defined)
- ✅ Maintenance sections (update triggers + verification)
- ✅ README hub (central navigation)
- ✅ DAG structure (Directed Acyclic Graph navigation)
- ✅ Living documentation ready
- ✅ Deduplicated content (canonical sources only)
- ✅ Validated cross-links (no broken links)
3. Recommend next steps:
- "Review generated documentation (CLAUDE.md → docs/)"
- "Open docs/presentation/presentation_final.html in browser"
- "Run ln-210-epic-coordinator to decompose scope into Epics"
- "Share documentation with technical stakeholders"
**Output**: Summary message with file list and recommendations
---
## Complete Output Structure
```
project_root/
├── CLAUDE.md # ← Project entry point (link to docs/)
├── docs/
│ ├── README.md # ← Root documentation hub (general standards)
│ ├── documentation_standards.md # ← 60 universal requirements (Claude Code + industry standards)
│ ├── principles.md # ← 11 development principles (Standards First, YAGNI, KISS, DRY, etc.)
│ ├── project/
│ │ ├── requirements.md # ← Functional Requirements (NO NFR per project policy)
│ │ ├── architecture.md # ← arc42-based architecture with C4 Model
│ │ ├── tech_stack.md # ← Technology versions, Docker config
│ │ ├── api_spec.md # ← API endpoints (conditional)
│ │ ├── database_schema.md # ← Database schema (conditional)
│ │ ├── design_guidelines.md # ← UI/UX system (conditional)
│ │ └── runbook.md # ← Operations guide (conditional)
│ ├── reference/
│ │ ├── README.md # ← Reference documentation hub (registries)
│ │ ├── adrs/ # ← Empty, ready for ADRs
│ │ ├── guides/ # ← Empty, ready for guides
│ │ └── manuals/ # ← Empty, ready for manuals
│ ├── tasks/
│ │ ├── README.md # ← Task management system rules
│ │ └── kanban_board.md # ← Linear integration (optional)
│ └── presentation/
│ ├── README.md # ← Navigation hub for presentation
│ ├── presentation_final.html # ← Final standalone HTML (~130-180 KB)
│ └── assets/ # ← Modular HTML structure
└── tests/
└── README.md # ← Test documentation (optional)
```
---
## Integration with Project Workflow
**Recommended workflow for new projects:**
1. **ln-110-documents-pipeline** (this skill) - Create complete documentation system
2. **ln-210-epic-coordinator** - Decompose scope into Epics (Linear Projects)
3. **ln-220-story-coordinator** - Create User Stories for each Epic (automatic decomposition + replan)
4. **ln-310-story-decomposer** - Break down Stories into implementation tasks (automatic decomposition + replan)
5. **ln-320-story-validator** - Verify Stories before development
6. **ln-330-story-executor** - Orchestrate Story implementation
7. **ln-340-story-quality-gate** - Review completed Stories
---
## Advantages of Orchestrator Approach
**Benefits:**
- ✅ Single command creates complete system
- ✅ No need to remember skill sequence
- ✅ Automated skill chaining
- ✅ Consistent output every time
- ✅ Time-saving (one invocation vs 2-3 manual invocations)
- ✅ **Idempotent**: Safe to run multiple times - preserves existing files, creates only missing ones
- ✅ **Pre-flight check**: Shows file scan summary before execution
- ✅ **Global cleanup**: Automatic deduplication, orphaned files archival, knowledge consolidation
- ✅ **Validated cross-links**: No broken links in documentation
**Trade-offs:**
- ⚠️ Less granular control (can't skip ln-111-docs-creator phases)
- ⚠️ Longer execution time (15-20 minutes)
- ⚠️ Global cleanup runs even if only one file was created
**When to use manual approach instead:**
- Need only HTML rebuild → use [ln-115-presentation-creator](../ln-115-presentation-creator/SKILL.md)
- Need one specific ADR → use [ln-322-adr-creator](../ln-322-adr-creator/SKILL.md)
---
## Error Handling
If any invoked skill fails:
1. Notify user which skill failed
2. Show error message from failed skill
3. Recommend manual invocation for debugging
4. List already completed steps (partial progress)
---
## Technical Implementation Notes
**Skill Invocation:**
- Uses **Skill tool** with command parameter
- Waits for each skill to complete before proceeding
- Verifies output files exist before moving to next phase
**File Verification:**
- Uses **Glob** tool to check docs/project/ structure
- Lists file sizes for user confirmation
- Warns if expected files missing
**Global Cleanup:**
- Uses **Glob** tool to find all .md files
- Uses **Read** tool to analyze content
- Uses **Edit** tool to remove duplicates and add links
- Uses **Bash** tool to archive orphaned files
**Standards Compliance:**
- All output follows same standards as underlying skills
- ISO/IEC/IEEE 29148:2018 (Requirements)
- ISO/IEC/IEEE 42010:2022 (Architecture)
- arc42 + C4 Model + Michael Nygard's ADR Format
---
## Definition of Done
Before completing work, verify ALL checkpoints:
**✅ User Confirmation (Phase 1):**
- [ ] Workflow explained to user (6 workers: ln-111 → ln-112 → ln-113 → ln-114 → ln-115 → ln-116)
- [ ] User approved: "Proceed with complete documentation system creation? (yes/no)"
- [ ] Test docs preference captured: "Include test documentation? (yes/no)"
**✅ Workers Invoked Sequentially (Phase 2):**
- [ ] ln-111-root-docs-creator invoked → Output verified: `CLAUDE.md` + `docs/README.md` + `docs/documentation_standards.md` + `docs/principles.md`
- [ ] ln-112-reference-docs-creator invoked → Output verified: `docs/reference/README.md` + directories (adrs/, guides/, manuals/)
- [ ] ln-113-tasks-docs-creator invoked → Output verified: `docs/tasks/README.md` + optionally `kanban_board.md`
- [ ] ln-114-project-docs-creator invoked → Output verified: `docs/project/requirements.md`, `architecture.md`, `tech_stack.md` + conditional documents (3-7 files)
- [ ] ln-115-presentation-creator invoked → Output verified: `docs/presentation/README.md` + `presentation_final.html` + `assets/`
- [ ] ln-116-test-docs-creator invoked (if enabled) → Output verified: `tests/README.md`
- [ ] Each worker validated its own output (SCOPE tags, Maintenance sections, POSIX compliance)
**✅ File Verification Complete:**
- [ ] All expected files exist (Glob tool used to verify structure)
- [ ] File sizes listed for user confirmation
- [ ] Warning displayed if expected files missing
**✅ Global Cleanup Complete (Phase 4):**
- [ ] 4.1: Duplicate sections identified and removed (>80% similarity)
- [ ] 4.1: Links added to canonical locations (principles.md, testing-strategy.md, kanban_board.md)
- [ ] 4.2: Orphaned files archived to `.archive/YYYY-MM-DD/`
- [ ] 4.3: Scattered concepts consolidated to Single Source of Truth (SSoT)
- [ ] 4.4: Internal links validated (broken links fixed, critical links added)
- [ ] 4.5: Final report generated (counts, lists, actions)
**✅ Summary Displayed (Phase 5):**
- [ ] All created files listed with sizes
- [ ] Documentation system features highlighted (SCOPE tags, Maintenance sections, README hubs, DAG structure, deduplicated content, validated links)
- [ ] Next steps recommended (ln-210-epic-coordinator)
**✅ Error Handling (if applicable):**
- [ ] If any worker failed: User notified which worker failed, error message shown, manual invocation recommended, partial progress listed
**Output:** Complete documentation system (CLAUDE.md + docs/ with README.md, documentation_standards.md, principles.md + presentation/ + optionally tests/) with global cleanup (no duplicates, no orphaned files, consolidated knowledge, validated cross-links)
---
**Version:** 6.0.0 (MAJOR: Removed Phase 3 validation - delegated to workers Phase 2/3. Added Phase 4 Global Cleanup: deduplication, orphaned files, consolidation, cross-link validation. Orchestrator now coordinates workers (Phase 2) + global operations (Phase 4). All workers are idempotent.)
**Last Updated:** 2025-11-18

123
skills/ln-110-documents-pipeline/diagram.html Normal file
View File

@@ -0,0 +1,123 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>ln-110-documents-pipeline - State Diagram</title>
<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
<link rel="stylesheet" href="../shared/css/diagram.css">
</head>
<body>
<div class="container">
<header>
<h1>🎯 ln-110-documents-pipeline</h1>
<p class="subtitle">Documentation Pipeline Orchestrator - State Diagram</p>
</header>
<div class="info-box">
<h3>📋 Workflow Overview</h3>
<ul>
<li><strong>Purpose:</strong> Create complete documentation system (CLAUDE.md + docs/ + presentation/) in one command</li>
<li><strong>Orchestrates:</strong> 6 workers (ln-111 → ln-112 → ln-113 → ln-114 → ln-115 → ln-116)</li>
<li><strong>Phases:</strong> 5 phases (Phase 1 User Confirmation → Phase 2 Worker Invocation → Phase 4 Global Cleanup → Phase 5 Summary)</li>
<li><strong>Error handling:</strong> Stops if any invoked worker fails</li>
</ul>
</div>
<div class="legend">
<div class="legend-item">
<div class="legend-color color-action"></div>
<span>Orchestration Action</span>
</div>
<div class="legend-item">
<div class="legend-color color-decision"></div>
<span>Completion Check</span>
</div>
<div class="legend-item">
<div class="legend-color color-error"></div>
<span>Error State</span>
</div>
</div>
<div class="diagram-container">
<div class="mermaid">
graph TD
Start([Start: ln-110-documents-pipeline]) --> Phase1[Phase 1: User Confirmation<br/>Explain workflow + get approval]
Phase1 --> Approved{User<br/>approved?}
Approved -->|No| Cancelled([Cancelled by user])
Approved -->|Yes| W1[Phase 2.1: Invoke ln-111-root-docs-creator<br/>CLAUDE.md + docs/README.md]
W1 --> W1Check{ln-111<br/>completed?}
W1Check -->|No| Error[Error: Worker failed]
W1Check -->|Yes| W2[Phase 2.2: Invoke ln-112-reference-docs-creator<br/>docs/reference/ structure]
W2 --> W2Check{ln-112<br/>completed?}
W2Check -->|No| Error
W2Check -->|Yes| W3[Phase 2.3: Invoke ln-113-tasks-docs-creator<br/>docs/tasks/ + kanban_board.md]
W3 --> W3Check{ln-113<br/>completed?}
W3Check -->|No| Error
W3Check -->|Yes| W4[Phase 2.4: Invoke ln-114-project-docs-creator<br/>docs/project/ documentation]
W4 --> W4Check{ln-114<br/>completed?}
W4Check -->|No| Error
W4Check -->|Yes| W5[Phase 2.5: Invoke ln-115-presentation-creator<br/>docs/presentation/ HTML]
W5 --> W5Check{ln-115<br/>completed?}
W5Check -->|No| Error
W5Check -->|Yes| W6[Phase 2.6: Invoke ln-116-test-docs-creator<br/>tests/README.md optional]
W6 --> W6Check{ln-116<br/>completed?}
W6Check -->|No| Error
W6Check -->|Yes| Phase4[Phase 4: Global Cleanup<br/>Deduplication + Orphan removal<br/>Consolidation + Cross-link validation]
Phase4 --> Phase4Check{Phase 4<br/>completed?}
Phase4Check -->|No| Error
Phase4Check -->|Yes| Summary[Phase 5: Summary<br/>Display completion report]
Summary --> End([End: Documentation created])
Error --> End
Cancelled --> End
%% Styling
classDef action fill:#C8E6C9,stroke:#388E3C,stroke-width:2px
classDef decision fill:#FFE0B2,stroke:#E64A19,stroke-width:2px
classDef error fill:#FFCDD2,stroke:#C62828,stroke-width:2px
class Phase1,W1,W2,W3,W4,W5,W6,Phase4,Summary action
class Approved,W1Check,W2Check,W3Check,W4Check,W5Check,W6Check,Phase4Check decision
class Error error
</div>
</div>
<div class="info-box">
<h3>🔑 Key Features</h3>
<ul>
<li><strong>One Command:</strong> Creates entire documentation system in single invocation</li>
<li><strong>Sequential Execution:</strong> 6 workers invoked in order (15-20 minutes total)</li>
<li><strong>Global Cleanup:</strong> Phase 4 removes duplicates, orphaned files, consolidates knowledge, validates cross-links</li>
<li><strong>Domain Separation:</strong> Each worker creates specific documentation area</li>
<li><strong>Error Handling:</strong> Stops execution if any worker fails, shows partial progress</li>
</ul>
</div>
<footer>
<p>Generated for ln-110-documents-pipeline skill | Version 6.0.0</p>
<p>Diagram format: Mermaid.js | Last updated: 2025-11-18</p>
</footer>
</div>
<script>
mermaid.initialize({
startOnLoad: true,
theme: 'default',
flowchart: {
useMaxWidth: true,
htmlLabels: true,
curve: 'basis'
}
});
</script>
</body>
</html>

444
skills/ln-111-root-docs-creator/SKILL.md Normal file
View File

@@ -0,0 +1,444 @@
---
name: ln-111-root-docs-creator
description: Creates root documentation (CLAUDE.md + docs/README.md + documentation_standards.md + principles.md). First worker in ln-110-documents-pipeline. Establishes documentation structure and standards.
---
# Root Documentation Creator
This skill creates the root documentation entry points for a project: CLAUDE.md (project root), docs/README.md (documentation hub with general standards), docs/documentation_standards.md (60 universal documentation requirements), and docs/principles.md (11 development principles).
## When to Use This Skill
**This skill is a WORKER** invoked by **ln-110-documents-pipeline** orchestrator.
This skill should be used directly when:
- Creating only root documentation files (CLAUDE.md + docs/README.md + documentation_standards.md + principles.md)
- Setting up documentation structure for existing project
- NOT creating full documentation structure (use ln-110-documents-pipeline for complete setup)
## How It Works
The skill follows a 3-phase workflow: **CREATE** → **VALIDATE STRUCTURE** → **VALIDATE CONTENT**. Each phase builds on the previous, ensuring complete structure and semantic validation.
---
### Phase 1: Create Structure
**Objective**: Create all 4 root documentation files.
**Process**:
**1.1 Create CLAUDE.md**:
- Check if CLAUDE.md exists in project root
- If exists:
- Read first 50 lines
- Check for link to `docs/README.md`
- If missing:
- Use Edit tool to add Documentation section:
```markdown
## Documentation
Project documentation: [docs/README.md](docs/README.md)
```
- Log: "✓ Added docs link to existing CLAUDE.md"
- If present:
- Log: "✓ CLAUDE.md already has docs link"
- If NOT exists:
- Ask user: "Project name?"
- Ask user: "Brief project description (1-2 sentences)?"
- Copy template: `references/claude_md_template.md` → `CLAUDE.md`
- Replace placeholders:
- `{{PROJECT_NAME}}` — user input
- `{{PROJECT_DESCRIPTION}}` — user input
- `{{DATE}}` — current date (YYYY-MM-DD)
- Log: "✓ Created CLAUDE.md"
**1.2 Create docs/README.md**:
- Check if docs/README.md exists
- If exists:
- Skip creation
- Log: "✓ docs/README.md already exists"
- If NOT exists:
- Create docs/ directory if missing
- Copy template: `references/docs_root_readme_template.md` → `docs/README.md`
- Ask user: "Documentation status? (Draft/Active)"
- Replace placeholders:
- `{{VERSION}}` — "1.0.0"
- `{{DATE}}` — current date (YYYY-MM-DD)
- `{{STATUS}}` — user input
- Log: "✓ Created docs/README.md"
**1.3 Create docs/documentation_standards.md**:
- Check if docs/documentation_standards.md exists
- If exists:
- Skip creation
- Log: "✓ docs/documentation_standards.md already exists"
- If NOT exists:
- Copy template: `references/documentation_standards_template.md` → `docs/documentation_standards.md`
- Replace placeholders:
- `{{DATE}}` — current date (YYYY-MM-DD)
- `{{PROJECT_NAME}}` — from 1.1 (if collected)
- Log: "✓ Created docs/documentation_standards.md"
**1.4 Create docs/principles.md**:
- Check if docs/principles.md exists
- If exists:
- Skip creation
- Log: "✓ docs/principles.md already exists"
- If NOT exists:
- Copy template: `references/principles_template.md` → `docs/principles.md`
- Replace placeholders:
- `{{DATE}}` — current date (YYYY-MM-DD)
- Log: "✓ Created docs/principles.md"
**1.5 Output**:
```
CLAUDE.md # Created or updated with docs link
docs/
├── README.md # Created or existing
├── documentation_standards.md # Created or existing
└── principles.md # Created or existing
```
---
### Phase 2: Validate Structure
**Objective**: Ensure all 4 files comply with structural requirements and auto-fix violations.
**Process**:
**2.1 Check SCOPE tags**:
- Read first 10 lines of CLAUDE.md
- Check for `> **SCOPE:**` or `<!-- SCOPE: ... -->` tag
- If missing:
- Use Edit tool to add SCOPE tag after first heading:
```markdown
> **SCOPE:** Entry point with project overview and navigation ONLY.
```
- Track violation: `scope_tag_added_claude = True`
- Read first 10 lines of docs/README.md
- Check for `<!-- SCOPE: ... -->` tag
- If missing:
- Use Edit tool to add SCOPE tag after version info:
```markdown
<!-- SCOPE: Root documentation hub with general standards and navigation ONLY. -->
```
- Track violation: `scope_tag_added_docs_readme = True`
- Read first 10 lines of docs/principles.md
- Check for `> **SCOPE:**` or `<!-- SCOPE: ... -->` tag
- If missing:
- Use Edit tool to add SCOPE tag
- Track violation: `scope_tag_added_principles = True`
**2.2 Check required sections (parametric loop)**:
Define file parameters:
```
files = [
{
"path": "CLAUDE.md",
"sections": ["Documentation", "Documentation Maintenance Rules", "Maintenance"]
},
{
"path": "docs/README.md",
"sections": ["General Documentation Standards", "Writing Guidelines", "Maintenance"]
},
{
"path": "docs/documentation_standards.md",
"sections": ["Quick Reference", "Maintenance"]
},
{
"path": "docs/principles.md",
"sections": ["Decision-Making Framework", "Verification Checklist", "Maintenance"]
}
]
```
For each file in files:
1. Read file content
2. For each required section:
- Check if `## [Section Name]` header exists
- If missing:
- Use Edit tool to add section with placeholder:
```markdown
## [Section Name]
{{PLACEHOLDER}}
```
- Track violation: `missing_sections[file] += 1`
**2.3 Check Maintenance sections**:
- For each file in [CLAUDE.md, docs/README.md, docs/documentation_standards.md, docs/principles.md]:
- Search for `## Maintenance` header
- If missing:
- Use Edit tool to add at end of file:
```markdown
## Maintenance
**Update Triggers:**
- [To be defined]
**Verification:**
- [ ] All links resolve to existing files
- [ ] All placeholders replaced with content
**Last Updated:** [current date]
```
- Track violation: `maintenance_added[file] = True`
**2.4 Check POSIX file endings**:
- For each file:
- Check if file ends with single blank line
- If missing:
- Use Edit tool to add final newline
- Track fix: `posix_fixed[file] = True`
**2.5 Report validation**:
- Log summary:
```
✅ Structure validation complete:
- SCOPE tags: [count] files fixed
- Missing sections: [count] sections added across [count] files
- Maintenance sections: [count] files fixed
- POSIX endings: [count] files fixed
```
- If violations found: "⚠️ Auto-fixed [total] structural violations"
---
### Phase 3: Validate Content
**Objective**: Ensure each file answers its questions with meaningful content.
**Process**:
**3.1 Load validation spec**:
- Read `references/questions.md`
- Parse questions and validation heuristics for all 4 files
**3.2 Validate files (parametric loop)**:
Define file parameters:
```
files = [
{
"path": "CLAUDE.md",
"question": "Where is project documentation located and how to navigate it?",
"heuristics": [
"Contains link: [docs/README.md](docs/README.md)",
"Has SCOPE tag in first 10 lines",
"Contains 'Documentation Navigation Rules' section",
"Length > 80 words"
],
"auto_discovery": ["Check package.json for name/description"]
},
{
"path": "docs/README.md",
"question": "What is the documentation structure and what are general standards?",
"heuristics": [
"Contains SCOPE tag",
"Has 'General Documentation Standards' section",
"Has 'Writing Guidelines' section",
"Mentions SCOPE Tags, Maintenance Sections, Sequential Numbering",
"Length > 100 words"
],
"auto_discovery": ["Scan docs/ structure for subdirectories"]
},
{
"path": "docs/documentation_standards.md",
"question": "What are the comprehensive documentation requirements?",
"heuristics": [
"Contains 'Quick Reference' section with table",
"Has 12+ main sections (##)",
"File size > 300 lines",
"Mentions ISO/IEC/IEEE, DIATAXIS, arc42"
],
"auto_discovery": []
},
{
"path": "docs/principles.md",
"question": "What are the development principles and decision framework?",
"heuristics": [
"Contains SCOPE tag",
"Lists 11 principles",
"Has 'Decision-Making Framework' section",
"Has 'Verification Checklist' section",
"File size > 300 lines"
],
"auto_discovery": []
}
]
```
For each file in files:
1. **Read file content**:
- Extract full file content
2. **Check if content answers question**:
- Apply validation heuristics
- If ANY heuristic passes → content valid, skip to next file
- If ALL fail → content invalid, continue
3. **Auto-discovery** (if content invalid or placeholder present):
- **CLAUDE.md**:
- Check package.json for "name" and "description"
- If found, suggest to user: "Would you like to use '{name}' and '{description}' from package.json?"
- **docs/README.md**:
- Scan docs/ directory for subdirectories (project/, reference/, tasks/)
- Generate navigation links dynamically
- **docs/documentation_standards.md**, **docs/principles.md**:
- Use template as-is (universal standards)
- No auto-discovery needed
4. **Skip external API calls**:
- Templates already complete with universal standards
- No MCP Ref needed
**3.3 Report content validation**:
- Log summary:
```
✅ Content validation complete:
- Files checked: 4
- Already valid: [count]
- Auto-discovery applied: [count]
- Template content used: [count]
```
---
## Complete Output Structure
```
project_root/
├── CLAUDE.md # ← Project entry point with link to docs/
└── docs/
├── README.md # ← Root documentation hub (general standards)
├── documentation_standards.md # ← Documentation requirements (60 universal requirements)
└── principles.md # ← Development principles (11 principles + Decision Framework + Verification Checklist)
```
**Note**: Other documentation (project/, reference/, tasks/, presentation/) created by other workers in ln-110-documents-pipeline workflow.
---
## Reference Files Used
### Templates
**CLAUDE.md Template**:
- `references/claude_md_template.md` - Minimal CLAUDE.md with documentation link
**Root README Template**:
- `references/docs_root_readme_template.md` (v1.1.0) - Root documentation hub with:
- Overview (documentation system organization)
- General Documentation Standards (SCOPE Tags, Maintenance Sections, Sequential Numbering, Placeholder Conventions)
- Writing Guidelines (Progressive Disclosure Pattern)
- Maintenance section (Update Triggers, Verification, Last Updated)
**Documentation Standards Template**:
- `references/documentation_standards_template.md` (v1.0.0) - Documentation requirements with:
- Quick Reference (60 universal requirements in 12 categories)
- Claude Code Integration (#26-30)
- AI-Friendly Writing Style (#31-36)
- Markdown Best Practices (#37-42)
- Code Examples Quality (#43-47)
- DIATAXIS Framework (#48-52)
- Project Files (#53-58)
- Visual Documentation (#67-71)
- Conventional Commits & Changelog (#72-75)
- Security & Compliance (#76-79)
- Performance & Optimization (#80-82)
- Project-Specific Customization Guide
- References (industry sources)
- Maintenance section
**Development Principles Template**:
- `references/principles_template.md` (v1.0.0) - Development principles with:
- 11 Core Principles (Standards First, YAGNI, KISS, DRY, Consumer-First Design, Task Granularity, Value-Based Testing, No Legacy Code, Token Efficiency, Documentation-as-Code, Security by Design)
- Decision-Making Framework (7 steps: Security → Standards → Correctness → Simplicity → Necessity → Maintainability → Performance)
- Trade-offs (when principles conflict)
- Anti-Patterns to Avoid
- Verification Checklist (11 items)
- Maintenance section
**Validation Specification**:
- `references/questions.md` (v1.0) - Question-driven validation:
- Questions each file must answer
- Validation heuristics
- Auto-discovery hints
---
## Best Practices
- **No premature validation**: Phase 1 creates structure, Phase 2 validates it (no duplicate checks)
- **Parametric validation**: Phases 2-3 use loops for 4 files (no code duplication)
- **Auto-discovery first**: Check package.json and docs/ structure before asking user
- **Idempotent**: ✅ Can run multiple times safely (checks existence before creation)
- **Separation of concerns**: CREATE → VALIDATE STRUCTURE → VALIDATE CONTENT
- **CLAUDE.md**: Keep minimal - only project name, description, and docs link
- **docs/README.md**: General standards only - NO project-specific content
- **SCOPE Tags**: Include in first 3-10 lines of all documentation files
---
## Prerequisites
**Invoked by**: ln-110-documents-pipeline orchestrator
**Requires**: None (first worker in chain)
**Creates**:
- CLAUDE.md (project entry point)
- docs/README.md (documentation hub)
- docs/documentation_standards.md (60 requirements)
- docs/principles.md (11 principles + Decision Framework)
- Validated structure and content
---
## Definition of Done
Before completing work, verify ALL checkpoints:
**✅ Structure Created:**
- [ ] CLAUDE.md exists in project root
- [ ] docs/ directory exists
- [ ] docs/README.md exists
- [ ] docs/documentation_standards.md exists
- [ ] docs/principles.md exists
**✅ Structure Validated:**
- [ ] SCOPE tags present in CLAUDE.md, docs/README.md, docs/principles.md
- [ ] Required sections present in all 4 files
- [ ] Maintenance sections present in all 4 files
- [ ] POSIX file endings compliant
**✅ Content Validated:**
- [ ] All files checked against questions.md
- [ ] CLAUDE.md has docs link
- [ ] docs/README.md has General Standards + Writing Guidelines
- [ ] docs/documentation_standards.md has Quick Reference + 12 sections
- [ ] docs/principles.md has 11 principles + Decision Framework + Verification Checklist
**✅ Reporting:**
- [ ] Phase 1 logged: creation summary
- [ ] Phase 2 logged: structural fixes (if any)
- [ ] Phase 3 logged: content validation (if any)
---
## Technical Details
**Standards**:
- ISO/IEC/IEEE 29148:2018 (Documentation standards)
- Progressive Disclosure Pattern (token efficiency)
**Language**: English only
---
**Version:** 10.0.0 (MAJOR: Applied ln-112 pattern - 4 phases → 3 phases, added questions.md for semantic validation, parametric validation loop, removed workflow coupling. No functionality change, pure architectural refactoring for consistency with ln-112 PoC.)
**Last Updated:** 2025-11-18

109
skills/ln-111-root-docs-creator/diagram.html Normal file
View File

@@ -0,0 +1,109 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>ln-111-root-docs-creator - State Diagram</title>
<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
<link rel="stylesheet" href="../shared/css/diagram.css">
</head>
<body>
<div class="container">
<header>
<h1>📝 ln-111-root-docs-creator</h1>
<p class="subtitle">Root Documentation Creator - State Diagram</p>
</header>
<div class="info-box">
<h3>📋 Workflow Overview</h3>
<ul>
<li><strong>Purpose:</strong> Create root documentation entry points (CLAUDE.md + docs/README.md + documentation_standards.md + principles.md)</li>
<li><strong>Worker for:</strong> ln-110-documents-pipeline orchestrator</li>
<li><strong>Phases:</strong> 3 phases (Phase 1 CREATE → Phase 2 Structure Validation → Phase 3 Semantic Content Validation)</li>
<li><strong>Validation:</strong> Phase 2/3 validation with questions.md (22 questions for 4 documents)</li>
<li><strong>Idempotent:</strong> Can be run multiple times safely</li>
</ul>
</div>
<div class="legend">
<div class="legend-item">
<div class="legend-color color-action"></div>
<span>Creation Action</span>
</div>
<div class="legend-item">
<div class="legend-color color-decision"></div>
<span>Conditional Check</span>
</div>
<div class="legend-item">
<div class="legend-color color-success"></div>
<span>Success State</span>
</div>
</div>
<div class="diagram-container">
<div class="mermaid">
graph TD
Start([Start: Root Docs Creation]) --> Phase1{CLAUDE.md exists?}
Phase1 -->|Yes| CheckLink{Has docs/README.md<br/>link?}
Phase1 -->|No| AskProject[Ask: Project name<br/>and description]
CheckLink -->|Yes| Phase2Start[Phase 2: Create docs/README.md]
CheckLink -->|No| AddLink[Add docs link<br/>to CLAUDE.md]
AskProject --> CreateClaude[Create CLAUDE.md<br/>from template]
CreateClaude --> CreateStandards[Create documentation_standards.md<br/>60 universal requirements]
CreateStandards --> CreatePrinciples[Create principles.md<br/>11 development principles]
CreatePrinciples --> Phase2Start
AddLink --> Phase2Start
Phase2Start --> CreateDir[Create docs/<br/>directory]
CreateDir --> CreateReadme[Create docs/README.md<br/>from template]
CreateReadme --> ReplaceVars[Replace placeholders:<br/>VERSION, DATE, STATUS]
ReplaceVars --> Phase2Validate[Phase 2: Structure Validation<br/>SCOPE tags, Maintenance sections]
Phase2Validate --> Phase3Validate[Phase 3: Semantic Content Validation<br/>questions.md Q1-Q22]
Phase3Validate --> Notify[Notify: Root structure<br/>established + validated]
Notify --> End([End: ✓ 4 docs created + validated])
%% Styling
classDef action fill:#C8E6C9,stroke:#388E3C,stroke-width:2px
classDef decision fill:#FFE0B2,stroke:#E64A19,stroke-width:2px
classDef success fill:#B3E5FC,stroke:#0277BD,stroke-width:2px
class AskProject,CreateClaude,CreateStandards,CreatePrinciples,AddLink,CreateDir,CreateReadme,ReplaceVars,Phase2Validate,Phase3Validate,Notify action
class Phase1,CheckLink decision
class End success
</div>
</div>
<div class="info-box">
<h3>🔑 Key Features</h3>
<ul>
<li><strong>First Worker:</strong> Establishes documentation structure and standards</li>
<li><strong>Idempotent:</strong> Skips if CLAUDE.md already has docs link</li>
<li><strong>Template-Based:</strong> Uses claude_md_template.md, docs_root_readme_template.md, documentation_standards_template.md, principles_template.md</li>
<li><strong>General Standards:</strong> docs/README.md contains SCOPE Tags, Maintenance Sections, Writing Guidelines</li>
<li><strong>Semantic Validation:</strong> Parametric validation loop with questions.md (Q1-Q22)</li>
</ul>
</div>
<footer>
<p>Generated for ln-111-root-docs-creator skill | Version 10.0.0</p>
<p>Diagram format: Mermaid.js | Last updated: 2025-11-18</p>
</footer>
</div>
<script>
mermaid.initialize({
startOnLoad: true,
theme: 'default',
flowchart: {
useMaxWidth: true,
htmlLabels: true,
curve: 'basis'
}
});
</script>
</body>
</html>

128
skills/ln-111-root-docs-creator/references/claude_md_template.md Normal file
View File

@@ -0,0 +1,128 @@
# {{PROJECT_NAME}}
{{PROJECT_DESCRIPTION}}
> **SCOPE:** Entry point with project overview and navigation ONLY. Contains project summary, documentation rules, and links to detailed docs. DO NOT add: business logic (→ Architecture.md + ADRs), principles (→ principles.md), API specs (→ api_spec.md), patterns (→ guides/).
## ⚠️ Critical Rules for AI Agents
**Read this table BEFORE starting any work.**
| Category | Rule | When to Apply | Rationale |
|----------|------|---------------|-----------|
| **Standards Hierarchy** | Industry Standards → Security → Principles | All work | ISO/IEC/IEEE, RFC, OWASP override YAGNI/KISS |
| **Documentation** | Read README before folder work | Before creating/editing files | Understand structure and conventions |
| **Documentation Navigation** | Read SCOPE tag first in each document | Before reading any doc | DAG structure - understand boundaries |
| **Testing** | Read tests/README.md before tests | Before test work | Story-Level Test Task Pattern |
| **Research** | Search MCP Ref before proposing changes | Before code changes | Official docs prevent reinventing wheel |
| **Task Management** | Linear MCP only, NO gh command | All task operations | See docs/tasks/README.md |
| **Skills** | Use built-in skills proactively | Documentation/Planning/Execution | Skills automate workflows |
| **Language** | English for all content, Russian for chat | All project content | Code/docs/tasks/commits in English only |
**Key Principles:**
- **Standards First**: Industry standards (ISO, RFC, OWASP, WCAG 2.1 AA) override development principles
- **Token Efficiency**: Progressive Disclosure Pattern (tables > paragraphs), no duplication
- **Quality**: Risk-Based Testing (2-5 E2E, 3-8 Integration, 5-15 Unit per Story)
- **No Legacy Code**: Remove backward compatibility shims immediately
---
## Documentation Navigation Rules
**Graph Structure:** All documentation organized as Directed Acyclic Graph (DAG) with CLAUDE.md as entry point.
**Reading Order:**
1. **Read SCOPE first** - Every document starts with `> **SCOPE:**` tag defining its boundaries
2. **Follow links down** - Navigate from parent to child documents through links
3. **Respect boundaries** - SCOPE tells you what IS and what IS NOT in each document
**Example Navigation:**
```
CLAUDE.md (SCOPE: Entry point, project overview)
→ Read SCOPE: "Contains project summary, NOT implementation details"
→ Need principles? Follow link → docs/principles.md
→ Read SCOPE: "Contains development principles, NOT architecture"
→ Need architecture? Follow link → docs/Architecture.md
```
---
## Documentation
Project documentation: [docs/README.md](docs/README.md)
Documentation standards: [docs/documentation_standards.md](docs/documentation_standards.md)
Development principles: [docs/principles.md](docs/principles.md)
## Development Commands
| Task | Windows | Bash |
|------|---------|------|
| **Install Dependencies** | `[Add your command]` | `[Add your command]` |
| **Run Tests** | `[Add your command]` | `[Add your command]` |
| **Start Dev Server** | `[Add your command]` | `[Add your command]` |
| **Build** | `[Add your command]` | `[Add your command]` |
| **Lint/Format** | `[Add your command]` | `[Add your command]` |
> [!NOTE]
> Update this table with project-specific commands during project setup
---
## Documentation Maintenance Rules
### For AI Agents (Claude Code)
**Principles:**
1. **Single Source of Truth:** Each fact exists in ONE place only - link, don't duplicate
2. **Graph Structure:** All docs reachable from `CLAUDE.md` → `docs/README.md` (DAG, no cycles)
3. **SCOPE Tag Required:** Every document MUST start with `> **SCOPE:**` tag defining boundaries (what IS and what IS NOT in document)
4. **DRY (Don't Repeat Yourself):** Reference existing docs instead of copying content
5. **Update Immediately:** When code changes, update related docs while context is fresh
6. **Context-Optimized:** Keep `CLAUDE.md` concise (≤100 lines recommended) - detailed info in `docs/`
7. **English Only:** ALL project content (code, comments, documentation, tasks, commit messages, variable names) MUST be in English
For document responsibilities and scope, see [docs/README.md](docs/README.md).
**Avoiding Duplication:**
**BAD:**
- Same architecture description in 3 files
- Development commands duplicated in multiple docs
- Full specs repeated across multiple guides
**GOOD:**
- `CLAUDE.md`: "See [docs/project/architecture.md](docs/project/architecture.md) for component structure (C4 diagrams)"
- Guides reference each other: "See [guide_name.md](./guide_name.md)"
- One canonical source per concept with links from other docs
**Best Practices (Claude Code 2025):**
- Use subagents for complex doc updates to avoid context pollution
- Update docs immediately after feature completion (context is fresh)
- Use `/clear` after big doc refactors to start fresh
- Keep `CLAUDE.md` as the always-loaded entry point with links to detailed docs
---
## Maintenance
**Update Triggers:**
- When changing project navigation (new/renamed docs)
- When updating critical rules for agents
- When modifying development commands
- When adding/removing key principles
- When documentation structure changes
**Verification:**
- [ ] All links resolve to existing files
- [ ] SCOPE tag clearly defines document boundaries
- [ ] Critical rules align with project requirements
- [ ] Command examples match actual project setup
- [ ] No duplicated content across documents
- [ ] Documentation Standards link correct
---
**Last Updated:** {{DATE}}

224
skills/ln-111-root-docs-creator/references/docs_root_readme_template.md Normal file
View File

@@ -0,0 +1,224 @@
# Documentation System
**Version:** {{VERSION}}
**Last Updated:** {{DATE}}
**Status:** {{STATUS}}
<!-- SCOPE: Root documentation hub with general standards and navigation ONLY. Contains documentation structure overview, SCOPE tags rules, maintenance conventions, sequential numbering, placeholder conventions. NO content duplication - all details in subdirectory READMEs. -->
<!-- DO NOT add here: Project-specific details → project/README.md, Reference documentation → reference/README.md, Task management rules → tasks/README.md, Implementation code → Task descriptions -->
---
## Overview
This documentation system provides comprehensive technical and operational documentation following industry standards (ISO/IEC/IEEE 29148, arc42, C4 Model, Michael Nygard's ADR format).
**Documentation is organized into three main areas:**
- **Project Documentation** - Requirements, architecture, technical specifications
- **Reference Documentation** - Architecture decisions (ADRs), reusable patterns (Guides), API references (Manuals)
- **Task Management** - Linear workflow, task tracking rules, kanban board
---
## General Documentation Standards
All documentation in this system follows these conventions:
### SCOPE Tags
Every document contains HTML comment tags defining its boundaries:
```html
<!-- SCOPE: What this document CONTAINS -->
<!-- DO NOT add here: What belongs elsewhere → where to find it -->
```
**Purpose**: Prevent content duplication, maintain single source of truth, redirect to correct location.
**Example**:
```html
<!-- SCOPE: Project requirements ONLY. Functional requirements ONLY. -->
<!-- DO NOT add here: Architecture details → architecture.md, Implementation → Task descriptions -->
```
### Maintenance Sections
All documents contain a **Maintenance** section with:
| Field | Description | Example |
|-------|-------------|---------|
| **Update Triggers** | When to update the document | "When changing acceptance criteria (Non-Functional Requirements are forbidden here)" |
| **Verification** | How to verify document is current | "Check all FR-XXX IDs referenced in tests exist" |
| **Last Updated** | Date of last modification | "2025-11-15" |
### Sequential Numbering
**Rule**: Phases/Sections/Steps use sequential integers: 1, 2, 3, 4 (NOT 1, 1.5, 2).
**Exceptions**:
| Case | Format | Example | When Valid |
|------|--------|---------|------------|
| **Conditional Branching** | Letter suffixes | Phase 4a (CREATE), Phase 4b (REPLAN), Phase 5 | Mutually exclusive paths (EITHER A OR B) |
| **Loop Internals** | Steps inside Phase | Phase 3: Loop → Step 1 → Step 2 → Repeat | Cyclic workflows with repeated sub-steps |
**Important**: When inserting new items, renumber all subsequent items.
### Placeholder Conventions
Documents use placeholders for registry updates:
| Placeholder | Location | Purpose | Updated By |
|-------------|----------|---------|------------|
| `{{ADR_LIST}}` | reference/README.md | ADR registry | ln-322-adr-creator |
| `{{GUIDE_LIST}}` | reference/README.md | Guide registry | ln-321-guide-creator |
| `{{MANUAL_LIST}}` | reference/README.md | Manual registry | ln-323-manual-creator |
**Usage**: Skills automatically add new entries BEFORE the placeholder using Edit tool.
### Writing Guidelines (Progressive Disclosure Pattern)
All documentation follows token-efficient formatting rules:
| Content Type | Format | Rationale |
|--------------|--------|-----------|
| **Skill descriptions** | < 200 chars in SKILL.md frontmatter | Clarity, focused scope |
| **Workflows** | Reference table with link to SKILL.md | Avoid duplication (DRY) |
| **Examples** | Table rows (verdict + rationale) | 60-80% more compact than paragraphs |
| **Lists** | Bullet points with inline details | Progressive disclosure |
| **References** | One-line format (source - topics - insight) | Scannable, no verbose paragraphs |
| **Comparisons** | Table with columns | Visual clarity, easy scanning |
| **Step-by-step processes** | Inline arrow notation (Step 1 → Step 2 → Step 3) | Compact flow representation |
**Verbose content is justified for:**
- ❌ Anti-patterns (educational value - prevents mistakes)
- 🎓 Complex architectural explanations (orchestrator patterns, state machines)
- ⚠️ Critical rules with rationale (INVEST criteria, task sizing)
**Compression targets:**
- Main documentation files: < 500 lines (optimal: 300-400 lines)
- README hubs: < 200 lines
- Individual guides: < 800 lines (optimal: 400-600 lines)
### Documentation Standards
**Full documentation requirements:** See [documentation_standards.md](documentation_standards.md)
Key highlights:
- **Claude Code Integration** - CLAUDE.md ≤100 lines, @-sourcing, sessionStart hooks
- **AI-Friendly Writing** - Second person, active voice, max 25 words/sentence
- **Code Examples** - All examples runnable, realistic names, show expected output
- **DIATAXIS Framework** - Organize docs into Tutorial/How-to/Reference/Explanation
- **Security** - Never commit secrets, use .env.example templates
- **Conventional Commits** - Structured commit messages for auto-changelog
**Total:** 60 requirements in 12 categories. See documentation_standards.md for complete details.
---
## Documentation Structure
### 1. [Project Documentation](project/README.md)
Core project documentation created by ln-114-project-docs-creator skill:
- **[README.md](project/README.md)** - Project documentation hub
- **[requirements.md](project/requirements.md)** - Functional requirements (FR-XXX-NNN) with MoSCoW prioritization
- **[architecture.md](project/architecture.md)** - System architecture (C4 Model, arc42)
- **[technical_specification.md](project/technical_specification.md)** - Implementation details
**Purpose**: Define WHAT we build and WHY.
**Created by**: ln-114-project-docs-creator
---
### 2. [Reference Documentation](reference/README.md)
Reusable knowledge base and architecture decisions:
- **[ADRs](reference/adrs/)** - Architecture Decision Records (format: `adr-NNN-slug.md`)
- **[Guides](reference/guides/)** - Project patterns and best practices (format: `NN-pattern-name.md`)
- **[Manuals](reference/manuals/)** - Package API references (format: `package-version.md`)
**Purpose**: Document HOW we build (patterns, decisions, APIs).
**Created by**: ln-322-adr-creator, ln-321-guide-creator, ln-323-manual-creator
---
### 3. [Task Management System](tasks/README.md)
Linear integration and workflow rules:
- **[README.md](tasks/README.md)** - Task lifecycle, Linear integration rules, workflow skills
- **[kanban_board.md](tasks/kanban_board.md)** - Live navigation to active tasks
**Purpose**: Define HOW we track and manage work.
**Created by**: ln-111-docs-creator (Phase 2, Phase 9-10)
---
## Standards Compliance
This documentation system follows:
| Standard | Application | Reference |
|----------|-------------|-----------|
| **ISO/IEC/IEEE 29148:2018** | Requirements Engineering | [requirements.md](project/requirements.md) |
| **ISO/IEC/IEEE 42010:2022** | Architecture Description | [architecture.md](project/architecture.md) |
| **arc42 Template** | Software architecture documentation | [architecture.md](project/architecture.md) |
| **C4 Model** | Software architecture visualization | [architecture.md](project/architecture.md) |
| **Michael Nygard's ADR Format** | Architecture Decision Records | [reference/adrs/](reference/adrs/) |
| **MoSCoW Prioritization** | Requirements prioritization | [requirements.md](project/requirements.md) |
---
## Contributing to Documentation
When updating documentation:
1. **Check SCOPE tags** at top of document to ensure changes belong there
2. **Update Maintenance > Last Updated** date in the modified document
3. **Update registry** if adding new documents:
- ADRs, Guides, Manuals → automatically updated by skills
- Project docs → update [project/README.md](project/README.md) manually
4. **Follow sequential numbering** rules (no decimals unless conditional branching)
5. **Add placeholders** if creating new document types
6. **Verify links** after structural changes
---
## Quick Navigation
| Area | Key Documents | Skills |
|------|---------------|--------|
| **Standards** | [documentation_standards.md](documentation_standards.md) | ln-111-root-docs-creator, ln-121-structure-validator |
| **Project** | [requirements.md](project/requirements.md), [architecture.md](project/architecture.md), [technical_specification.md](project/technical_specification.md) | ln-114-project-docs-creator, ln-122-content-updater |
| **Reference** | [ADRs](reference/adrs/), [Guides](reference/guides/), [Manuals](reference/manuals/) | ln-322-adr-creator, ln-321-guide-creator, ln-323-manual-creator |
| **Tasks** | [kanban_board.md](tasks/kanban_board.md), [README.md](tasks/README.md) | ln-210-epic-coordinator, ln-220-story-coordinator, ln-310-story-decomposer |
---
## Maintenance
**Update Triggers**:
- When adding new documentation areas (new subdirectories)
- When changing general documentation standards (SCOPE, Maintenance, Sequential Numbering)
- When changing writing guidelines or documentation formatting standards
- When adding new placeholder conventions
- When updating compliance standards
**Verification**:
- All links to subdirectory READMEs are valid
- SCOPE tags accurately reflect document boundaries
- Placeholder conventions documented for all registries
- Standards Compliance table references correct documents
**Last Updated**: {{DATE}}
---
**Template Version:** 1.1.0
**Template Last Updated:** 2025-11-16

160
skills/ln-111-root-docs-creator/references/documentation_standards_template.md Normal file
View File

@@ -0,0 +1,160 @@
# Documentation Standards
**Comprehensive Requirements for Claude Code Skills Documentation (2024-2025)**
**Last Updated:** {{DATE}}
<!-- SCOPE: 82 universal documentation requirements for Claude Code skills. Based on industry standards (ISO/IEC/IEEE, DIATAXIS, RFC), Claude Code best practices, and AI-friendly documentation research. NO project-specific details (→ project/requirements.md), NO skill-specific workflows (→ SKILL.md). -->
---
## Quick Reference (82 Requirements)
**Legend:** 🔴 Critical | 🟡 Important | 🟢 Desired | ⚠️ Conditional | ✅ Already implemented
| Category | Count | 🔴 | 🟡 | 🟢 | ⚠️ | ✅ | Validator |
|----------|-------|-----|-----|-----|-----|-----|-----------|
| **Core Documentation** | 25 | 8 | 12 | 5 | 0 | 0 | ln-121, ln-122 |
| **Claude Code Integration** | 5 | 1 | 2 | 2 | 0 | 0 | ln-121 v2.1.0+ |
| **AI-Friendly Writing** | 6 | 0 | 5 | 1 | 0 | 0 | ln-121 warning |
| **Markdown Best Practices** | 6 | 0 | 4 | 2 | 0 | 0 | ln-121 v2.1.0+ |
| **Code Examples Quality** | 5 | 1 | 2 | 2 | 0 | 0 | Manual + CI |
| **DIATAXIS Framework** | 5 | 0 | 1 | 2 | 0 | 2 | Manual |
| **Project Files** | 6 | 1 | 3 | 2 | 0 | 0 | Manual |
| **Quality Checks** | 5 | 0 | 4 | 1 | 0 | 0 | markdownlint, Vale |
| **Front Matter (SSG)** | 3 | 0 | 0 | 2 | 1 | 0 | Conditional |
| **Visual Documentation** | 5 | 0 | 0 | 4 | 0 | 1 | Manual |
| **Conventional Commits** | 4 | 0 | 1 | 1 | 0 | 2 | commitlint |
| **Security & Compliance** | 4 | 1 | 3 | 0 | 0 | 0 | Manual |
| **Performance** | 3 | 0 | 1 | 2 | 0 | 0 | Manual |
**Total:** 82 requirements | 🔴 12 Critical | 🟡 38 Important | 🟢 24 Desired | ⚠️ 1 Conditional | ✅ 5 Implemented
---
## Key Requirements by Priority
### Critical (Must Have)
| Requirement | Rationale | Validator |
|------------|-----------|-----------|
| CLAUDE.md ≤100 lines | Claude Code performance optimization | ln-121 v2.1.0+ |
| All code examples runnable | Prevent documentation drift | Manual + CI |
| LICENSE file exists | Legal compliance | Manual |
| Never commit secrets | Security breach prevention | Manual |
### Important (Should Have)
**Claude Code Integration:**
- @-sourcing support in CLAUDE.md (DRY pattern)
- Explicitly specify `setting_sources=["project"]`
**AI-Friendly Writing:**
- Use second person ("you" vs "users")
- Active voice instead of passive
- Short sentences (max 25 words)
- Prohibited phrases ("please note", "simply", "just", "easily")
- Don't assume prior knowledge
**Markdown Best Practices:**
- Header depth ≤ h3 (rarely h4)
- Descriptive links (not "click here")
- Callouts/Admonitions for important info
- Files end with single blank line (POSIX)
**Code Examples Quality:**
- Test documentation examples in CI/CD
- Include setup context (directory, prerequisites)
**Project Files:**
- CONTRIBUTING.md (contribution process)
- SECURITY.md (vulnerability reporting)
- .gitignore for docs (exclude generated files)
**Quality Checks:**
- markdownlint-cli2 (.markdownlint.jsonc)
- Vale.sh (.vale.ini for editorial checks)
- Build verification (prevent broken deployments)
- Link checking (dead link detection)
**Security & Compliance:**
- GitHub Secrets for CI/CD
- .env.example instead of .env
- Vulnerability reporting process (SECURITY.md)
**Performance:**
- Optimize CLAUDE.md size (-30 to -40% tokens via @-sourcing)
### Desired (Nice to Have)
**Documentation Structure:** DIATAXIS framework (Tutorial/How-to/Reference/Explanation sections), How-to guides ✅, Reference docs ✅
**Visual Elements:** Mermaid diagrams ✅, workflow diagrams, sequence diagrams, light/dark theme support, centralized image storage
**Version Control:** Conventional Commits format, auto-generate CHANGELOG, Keep a Changelog ✅, Semantic versioning ✅
**Code Quality:** Realistic variable names (not foo/bar), show expected output, code blocks in step lists
**Project Files:** CODE_OF_CONDUCT.md, README badges, vocabulary files for terminology
**Advanced Features:** SessionStart hooks, subagents in .claude/agents/*.md, Front Matter for SSG (Hugo/Docusaurus) ⚠️, lazy loading, caching strategy
**Writing Style:** Avoid first-person pronouns, Title case for h1/Sentence case for h2+
---
## Standards Compliance
| Standard | Reference |
|----------|-----------|
| **ISO/IEC/IEEE 29148:2018** | Requirements Engineering |
| **ISO/IEC/IEEE 42010:2022** | Architecture Description |
| **DIATAXIS Framework** | diataxis.fr - Documentation structure |
| **RFC 2119, WCAG 2.1 AA** | Requirement keywords, Accessibility |
| **OWASP Top 10** | Security requirements |
| **Conventional Commits** | conventionalcommits.org |
| **Keep a Changelog** | Changelog format |
| **Semantic Versioning** | Major.Minor.Patch |
**Sources:** Claude Code docs, Clever Cloud guide, DIATAXIS framework, Matter style guide
---
## Verification Checklist
Before submitting documentation:
- [ ] **CLAUDE.md ≤100 lines** - Concise and focused
- [ ] **All code examples runnable** - No placeholders, tested
- [ ] **LICENSE file exists** - Legal compliance
- [ ] **No secrets committed** - API keys in .env only
- [ ] **Header depth ≤ h3, files end with blank line** - Markdown standards
- [ ] **Active voice, second person, short sentences** - AI-friendly writing
- [ ] **SCOPE tag in docs/**, Maintenance section** - Core requirements
- [ ] **Descriptive links, callouts for important info** - Best practices
---
## Maintenance
**Update Triggers:**
- When Claude Code releases new best practices
- When industry standards evolve (ISO/IEC/IEEE updates)
- When new validation tools become available
- When ln-121-structure-validator or ln-122-content-updater add new checks
- Annual review (Q1 each year)
**Verification:**
- [ ] All 82 requirements documented with rationale
- [ ] Priority levels assigned (Critical/Important/Desired)
- [ ] Validators identified for automated checks
- [ ] Standards compliance table complete
- [ ] References link to authoritative sources
- [ ] Verification checklist covers all critical requirements
**Last Updated:** {{DATE}}
---
**Template Version:** 2.0.0 (MAJOR: Progressive Disclosure - reduced from 390→160 lines (-59%), removed detailed sections 1-12 and Implementation Roadmap, converted to compact table format, added SCOPE tag)
**Template Last Updated:** {{DATE}}

110
skills/ln-111-root-docs-creator/references/principles_template.md Normal file
View File

@@ -0,0 +1,110 @@
# Development Principles
**Last Updated:** {{DATE}}
<!-- SCOPE: Universal development principles for THIS project ONLY. Contains 8 core principles with rationale, Decision Framework, and Verification Checklist. NO implementation details (→ Architecture.md), NO project-specific requirements (→ Requirements.md), NO testing philosophy (→ docs/reference/guides/testing-strategy.md). -->
---
## Core Principles
| # | Name | Type | Principle | Approach/Rules |
|---|------|------|-----------|----------------|
| **1** | **Standards First** | code+docs | Industry standards (ISO/RFC/OWASP/WCAG) override development principles | **Hierarchy:** Industry Standards → Security Standards → Accessibility Standards → Dev Principles (YAGNI/KISS/DRY within standard boundaries) |
| **2** | **YAGNI (You Aren't Gonna Need It)** | code+docs | Don't build features "just in case". Build what's needed NOW | **Avoid:** Generic frameworks for one use case, caching without bottleneck, extensibility points without requirements |
| **3** | **KISS (Keep It Simple)** | code+docs | Simplest solution that solves the problem. No unnecessary complexity | **Approach:** Start with naive solution → Add complexity ONLY when proven necessary → Each abstraction layer must justify existence |
| **4** | **DRY (Don't Repeat Yourself)** | code+docs | Each piece of knowledge exists in ONE place. Link, don't duplicate | **Code:** Extract repeated logic, constants defined once. **Docs:** Single Source of Truth, reference via links, update immediately |
| **5** | **Consumer-First Design** | code | Design APIs/functions/workflows from consumer's perspective | **Design:** 1. Define interface/API FIRST (what consumers need) → 2. Implement internals SECOND (how it works) → 3. Never expose internal complexity to consumers. **Note:** This is for API/interface DESIGN, not task execution order (see Foundation-First Execution in workflow) |
| **6** | **No Legacy Code** | code | Remove backward compatibility shims immediately after migration | **Rules:** Deprecated features deleted in NEXT release (not "someday"), NO commented-out code (use git history), NO `if legacy_mode:` branches |
| **7** | **Documentation-as-Code** | docs | Documentation lives WITH code, updated WITH code changes | **Rules:** Documentation in same commit as code, NO separate "docs update" tasks, Outdated docs = bug (same severity as code bug) |
| **8** | **Security by Design** | code | Security integrated from design phase, not bolted on later | **Practices:** Never commit secrets → env vars/secret managers, Validate at boundaries → Pydantic models, Least Privilege → minimum permissions, Fail Securely → don't leak info in errors, Defense in Depth → multiple security layers |
---
## Decision-Making Framework
When making technical decisions, evaluate against these principles **in order**:
1. **Security:** Is it secure by design? (OWASP, NIST standards)
2. **Standards Compliance:** Does it follow industry standards? (ISO, RFC, W3C)
3. **Correctness:** Does it solve the problem correctly?
4. **Simplicity (KISS):** Is it the simplest solution that works?
5. **Necessity (YAGNI):** Do we actually need this now?
6. **Maintainability:** Can future developers understand and modify it?
7. **Performance:** Is it fast enough? (Optimize only if proven bottleneck)
### Trade-offs
When principles conflict, use the Decision-Making Framework hierarchy:
| Conflict | Lower Priority | Higher Priority | Resolution |
|----------|---------------|-----------------|------------|
| **Simplicity vs Security** | KISS | Security by Design | Choose secure solution, even if more complex |
| **YAGNI vs Standards** | YAGNI | Standards First | Implement standard now (e.g., OAuth 2.0), not "simple custom auth" |
| **Flexibility vs Constraints** | Flexibility | YAGNI | Choose constraints (clear boundaries), not open-ended "for future" |
---
## Anti-Patterns to Avoid
### God Objects
- ❌ One class/module that does everything
- ✅ Small, focused classes with single responsibility
### Premature Optimization
- ❌ Caching before measuring actual bottlenecks
- ✅ Measure first (profiling, metrics), optimize proven bottlenecks
### Over-Engineering
- ❌ Complex abstractions "for future flexibility"
- ✅ Simple solution now, refactor if complexity justified later
### Magic Numbers/Strings
- ❌ `if status == 200:` hardcoded everywhere
- ✅ `if status == HTTPStatus.OK:` or `STATUS_OK = 200` as constant
### Leaky Abstractions
- ❌ Service layer exposes database models to API layer
- ✅ Service layer returns DTOs/Pydantic schemas, hides ORM details
---
## Verification Checklist
Before submitting code, verify compliance with principles:
- [ ] **Standards First:** Follows industry standards (ISO, RFC, OWASP, WCAG 2.1 AA)
- [ ] **YAGNI:** Only building what's needed now (no speculative features)
- [ ] **KISS:** Solution is as simple as possible, not simpler
- [ ] **DRY:** No duplicated logic or documentation
- [ ] **Consumer-First Design:** API/interface designed from consumer perspective
- [ ] **No Legacy Code:** No deprecated code, no commented-out code
- [ ] **Documentation-as-Code:** Docs updated in same commit as code
- [ ] **Security by Design:** No secrets committed, input validated, least privilege
---
## Maintenance
**Update Triggers:**
- When adding new principles
- When changing decision framework hierarchy
- When industry standards evolve (ISO, RFC, OWASP updates)
- When trade-off examples change
- Annual review (Q1 each year)
**Verification:**
- [ ] All 8 principles documented
- [ ] Decision Framework clear (7 steps)
- [ ] Trade-offs explained (3 conflicts)
- [ ] Anti-patterns listed (5 patterns)
- [ ] Verification Checklist complete (8 items)
- [ ] Links to external resources valid
- [ ] Table format demonstrates principles clearly
**Last Updated:** {{DATE}}
---
**Template Version:** 3.0.0 (MAJOR: Removed domain-specific principles (Task Granularity→ln-113, Value-Based Testing→ln-116, Token Efficiency→documentation_standards.md), converted to table format (8 universal principles only), removed all detailed sections with examples for Progressive Disclosure)
**Template Last Updated:** {{DATE}}

475
skills/ln-111-root-docs-creator/references/questions.md Normal file
View File

@@ -0,0 +1,475 @@
# Root Documentation Questions
**Purpose:** Define what each root documentation file should answer. Each section maps explicitly to document sections for validation.
**Format:** Document → Rules → Questions (with target sections) → Validation Heuristics → Auto-Discovery
---
## Table of Contents
| Document | Questions | Auto-Discovery | Priority | Line |
|----------|-----------|----------------|----------|------|
| [CLAUDE.md](#claudemd) | 6 | Medium | Critical | L30 |
| [docs/README.md](#docsreadmemd) | 7 | Low | High | L170 |
| [docs/documentation_standards.md](#docsdocumentation_standardsmd) | 3 | None | Medium | L318 |
| [docs/principles.md](#docsprinciplesmd) | 6 | None | High | L381 |
**Priority Legend:**
- **Critical:** Must answer all questions
- **High:** Strongly recommended
- **Medium:** Optional (can use template defaults)
**Auto-Discovery Legend:**
- **None:** No auto-discovery needed (use template as-is)
- **Low:** 1-2 questions need auto-discovery
- **Medium:** 3+ questions need auto-discovery
---
<!-- DOCUMENT_START: CLAUDE.md -->
## CLAUDE.md
**File:** CLAUDE.md (project root)
**Target Sections:** ⚠️ Critical Rules for AI Agents, Documentation Navigation Rules, Documentation, Development Commands, Documentation Maintenance Rules, Maintenance
**Rules for this document:**
- Recommended length: ≤100 lines (guideline from Claude Code docs)
- Must have SCOPE tag in first 10 lines
- Must link to docs/README.md
- Entry point for all documentation (DAG root)
---
<!-- QUESTION_START: 1 -->
### Question 1: Where is project documentation located?
**Expected Answer:** Links to docs/README.md, documentation_standards.md, principles.md
**Target Section:** ## Documentation
**Validation Heuristics:**
- ✅ Has section "## Documentation" with links to docs/README.md, documentation_standards.md, principles.md
**Auto-Discovery:**
- None needed (standard structure)
<!-- QUESTION_END: 1 -->
---
<!-- QUESTION_START: 2 -->
### Question 2: What are critical rules for AI agents?
**Expected Answer:** Table of critical rules organized by category (Standards Hierarchy, Documentation, Testing, Research, Task Management, Skills, Language) with When to Apply and Rationale columns
**Target Section:** ## ⚠️ Critical Rules for AI Agents
**Validation Heuristics:**
- ✅ Has section "## ⚠️ Critical Rules for AI Agents" with table (Category, Rule, When to Apply, Rationale), 7+ rows, "Key Principles" subsection, mentions Standards First, Token Efficiency, Quality, No Legacy Code
**Auto-Discovery:**
- None needed (universal rules)
<!-- QUESTION_END: 2 -->
---
<!-- QUESTION_START: 3 -->
### Question 3: How to navigate documentation (DAG structure)?
**Expected Answer:** SCOPE tags explanation + reading order + graph structure with examples
**Target Section:** ## Documentation Navigation Rules
**Validation Heuristics:**
- ✅ Has section "## Documentation Navigation Rules" with SCOPE tag explanation, reading order (numbered list), example navigation, >40 words
**Auto-Discovery:**
- None needed (universal best practice)
<!-- QUESTION_END: 3 -->
---
<!-- QUESTION_START: 4 -->
### Question 4: What are documentation maintenance rules?
**Expected Answer:** DRY principles, Single Source of Truth, update triggers, English-only policy
**Target Section:** ## Documentation Maintenance Rules
**Validation Heuristics:**
- ✅ Has section "## Documentation Maintenance Rules" with "Single Source of Truth"/"DRY", "English Only" rule, "Principles"/"Avoiding Duplication" subsections, >60 words
**Auto-Discovery:**
- None needed (universal standards)
<!-- QUESTION_END: 4 -->
---
<!-- QUESTION_START: 5 -->
### Question 5: When should CLAUDE.md be updated?
**Expected Answer:** Update triggers + verification checklist
**Target Section:** ## Maintenance
**Validation Heuristics:**
- ✅ Has section "## Maintenance" with "Update Triggers" and "Verification" subsections, "Last Updated" field
**Auto-Discovery:**
- None needed (standard maintenance section)
<!-- QUESTION_END: 5 -->
---
<!-- QUESTION_START: 6 -->
### Question 6: What are the project development commands?
**Expected Answer:** Table with development commands organized by task (Install Dependencies, Run Tests, Start Dev Server, Build, Lint/Format) for both Windows and Bash
**Target Section:** ## Development Commands
**Validation Heuristics:**
- ✅ Has section "## Development Commands" with table (Task, Windows, Bash), 5+ rows, note about updating commands, placeholder/actual commands
**Auto-Discovery:**
- Scan package.json → "scripts" field (for Node.js projects)
- Scan pyproject.toml → [tool.poetry.scripts] or [project.scripts] (for Python projects)
- Scan Makefile → targets (for Make-based projects)
- Scan composer.json → "scripts" field (for PHP projects)
**Notes:**
- If no commands found, use placeholder: `[Add your command]`
- Auto-discovery hints can suggest common commands based on detected project type
<!-- QUESTION_END: 6 -->
---
**Overall File Validation:**
- ✅ Has SCOPE tag in first 10 lines
- ✅ Total length > 80 words (meaningful content)
**Auto-Discovery Hints:**
- Scan package.json → "name", "description" fields (for project name/description)
- Check existing CLAUDE.md for project name
<!-- DOCUMENT_END: CLAUDE.md -->
---
<!-- DOCUMENT_START: docs/README.md -->
## docs/README.md
**File:** docs/README.md (documentation hub)
**Target Sections:** Overview, General Documentation Standards, Writing Guidelines, Standards Compliance, Contributing to Documentation, Quick Navigation, Maintenance
**Rules for this document:**
- Must have SCOPE tag in first 10 lines (HTML comment)
- Hub file - navigation to subdirectories (project/, reference/, tasks/)
- General standards only - NO project-specific content
---
<!-- QUESTION_START: 1 -->
### Question 1: What is the documentation structure?
**Expected Answer:** Overview of documentation areas (Project, Reference, Task Management)
**Target Section:** ## Overview
**Validation Heuristics:**
- ✅ Has section "## Overview" mentioning Project Documentation (project/), Reference Documentation (reference/), Task Management (tasks/), >30 words
**Auto-Discovery:**
- Scan docs/ directory for subdirectories (project/, reference/, tasks/)
<!-- QUESTION_END: 1 -->
---
<!-- QUESTION_START: 2 -->
### Question 2: What are general documentation standards?
**Expected Answer:** SCOPE Tags, Maintenance Sections, Sequential Numbering, Placeholder Conventions
**Target Section:** ## General Documentation Standards
**Validation Heuristics:**
- ✅ Has section "## General Documentation Standards" with subsections (SCOPE Tags, Maintenance Sections, Sequential Numbering, Placeholder Conventions), >100 words
**Auto-Discovery:**
- None needed (universal standards)
<!-- QUESTION_END: 2 -->
---
<!-- QUESTION_START: 3 -->
### Question 3: What are writing guidelines?
**Expected Answer:** Progressive Disclosure Pattern, token efficiency, table-first format
**Target Section:** ## Writing Guidelines
**Validation Heuristics:**
- ✅ Has section "## Writing Guidelines" mentioning Progressive Disclosure/token efficiency, table/list with format guidelines, >50 words
**Auto-Discovery:**
- None needed (universal best practice)
<!-- QUESTION_END: 3 -->
---
<!-- QUESTION_START: 4 -->
### Question 4: When should docs/README.md be updated?
**Expected Answer:** Update triggers + verification checklist
**Target Section:** ## Maintenance
**Validation Heuristics:**
- ✅ Has section "## Maintenance" with "Update Triggers" and "Verification" subsections
**Auto-Discovery:**
- None needed (standard maintenance section)
<!-- QUESTION_END: 4 -->
---
<!-- QUESTION_START: 5 -->
### Question 5: What are the standards this documentation complies with?
**Expected Answer:** Standards Compliance table with Standard, Application, and Reference columns
**Target Section:** ## Standards Compliance
**Validation Heuristics:**
- ✅ Has section "## Standards Compliance" with table (Standard, Application, Reference), 5+ standards (ISO/IEC/IEEE 29148:2018, ISO/IEC/IEEE 42010:2022, arc42, C4 Model, ADR Format, MoSCoW), document path links
**Auto-Discovery:**
- None needed (universal standards)
<!-- QUESTION_END: 5 -->
---
<!-- QUESTION_START: 6 -->
### Question 6: How to contribute to documentation?
**Expected Answer:** Numbered list of contribution steps (Check SCOPE tags, Update Last Updated date, Update registry, Follow sequential numbering, Add placeholders, Verify links)
**Target Section:** ## Contributing to Documentation
**Validation Heuristics:**
- ✅ Has section "## Contributing to Documentation" with 6+ steps mentioning SCOPE tags, Last Updated, registry, sequential numbering, link verification, >40 words
**Auto-Discovery:**
- None needed (universal contribution guidelines)
<!-- QUESTION_END: 6 -->
---
<!-- QUESTION_START: 7 -->
### Question 7: How to quickly navigate to key documentation areas?
**Expected Answer:** Quick Navigation table with Area, Key Documents, and Skills columns
**Target Section:** ## Quick Navigation
**Validation Heuristics:**
- ✅ Has section "## Quick Navigation" with table (Area, Key Documents, Skills), 4 rows (Standards, Project, Reference, Tasks), document/skill name links
**Auto-Discovery:**
- Scan docs/ directory structure (project/, reference/, tasks/)
- Detect skill references from kanban_board.md (if exists)
<!-- QUESTION_END: 7 -->
---
**Overall File Validation:**
- ✅ Has SCOPE tag (HTML comment) in first 10 lines
- ✅ Total length > 100 words
<!-- DOCUMENT_END: docs/README.md -->
---
<!-- DOCUMENT_START: docs/documentation_standards.md -->
## docs/documentation_standards.md
**File:** docs/documentation_standards.md (60 universal requirements)
**Target Sections:** Quick Reference, 12 main sections (Claude Code Integration through References), Maintenance
**Rules for this document:**
- 60+ universal documentation requirements
- 12 main sections covering industry standards
- References to ISO/IEC/IEEE, DIATAXIS, arc42
---
<!-- QUESTION_START: 1 -->
### Question 1: What are the comprehensive documentation requirements?
**Expected Answer:** Quick Reference table with 60+ requirements in 12 categories
**Target Section:** ## Quick Reference
**Validation Heuristics:**
- ✅ Has section "## Quick Reference" with table (Requirement, Description, Priority, Reference), 60+ rows across categories (Claude Code Integration, AI-Friendly Writing, Markdown, Code Examples, DIATAXIS)
**Auto-Discovery:**
- None needed (universal standards, use template as-is)
<!-- QUESTION_END: 1 -->
---
<!-- QUESTION_START: 2 -->
### Question 2: What are the detailed requirements for each category?
**Expected Answer:** 12 main sections with detailed explanations
**Target Sections:** 12 sections (## Claude Code Integration, ## AI-Friendly Writing Style, etc.)
**Validation Heuristics:**
- ✅ Has 12+ main sections with subsections, mentions ISO/IEC/IEEE/DIATAXIS/arc42 standards, >300 lines
**Auto-Discovery:**
- None needed (universal standards)
<!-- QUESTION_END: 2 -->
---
<!-- QUESTION_START: 3 -->
### Question 3: When should documentation standards be updated?
**Expected Answer:** Update triggers + verification checklist
**Target Section:** ## Maintenance
**Validation Heuristics:**
- ✅ Has section "## Maintenance" with "Update Triggers" and "Verification" subsections
**Auto-Discovery:**
- None needed (standard maintenance section)
<!-- QUESTION_END: 3 -->
---
**Overall File Validation:**
- ✅ File size > 300 lines
- ✅ Mentions ISO/IEC/IEEE 29148:2018
- ✅ Mentions DIATAXIS framework
- ✅ Mentions arc42
**MCP Ref Hints:**
- Research: "DIATAXIS framework documentation" (if user wants customization)
- Research: "ISO/IEC/IEEE 29148:2018" (if user wants compliance details)
<!-- DOCUMENT_END: docs/documentation_standards.md -->
---
<!-- DOCUMENT_START: docs/principles.md -->
## docs/principles.md
**File:** docs/principles.md (8 development principles + Decision Framework)
**Target Sections:** Core Principles table, Decision-Making Framework, Trade-offs (subsection), Anti-Patterns, Verification Checklist, Maintenance
**Rules for this document:**
- Must have SCOPE tag in first 10 lines
- 8 core principles (Standards First, YAGNI, KISS, DRY, Consumer-First Design, No Legacy Code, Documentation-as-Code, Security by Design)
- Decision-Making Framework (7 steps)
- Verification Checklist (8 items)
---
<!-- QUESTION_START: 1 -->
### Question 1: What are the core development principles?
**Expected Answer:** 8 principles in table format (4 columns: Name, Type, Principle, Approach/Rules)
**Target Section:** ## Core Principles
**Validation Heuristics:**
- ✅ Has section "## Core Principles" with 8-row table (Name, Type, Principle, Approach/Rules): Standards First, YAGNI, KISS, DRY, Consumer-First Design, No Legacy Code, Documentation-as-Code, Security by Design, no subsections
**Auto-Discovery:**
- None needed (universal principles)
**Notes:**
- Task Granularity → Moved to ln-113-tasks-docs-creator (task management specific)
- Value-Based Testing → Moved to ln-116-test-docs-creator (testing specific)
- Token Efficiency → Referenced in documentation_standards.md (already detailed in #80-85)
<!-- QUESTION_END: 1 -->
---
<!-- QUESTION_START: 2 -->
### Question 2: How to make decisions when principles conflict?
**Expected Answer:** Decision-Making Framework with priority order (Security → Standards → Correctness → ...)
**Target Section:** ## Decision-Making Framework
**Validation Heuristics:**
- ✅ Has section "## Decision-Making Framework" with 7 steps (Security, Standards, Correctness, Simplicity, Necessity, Maintainability, Performance), >30 words
**Auto-Discovery:**
- None needed (universal framework)
<!-- QUESTION_END: 2 -->
---
<!-- QUESTION_START: 3 -->
### Question 3: How to resolve conflicts when principles contradict?
**Expected Answer:** Trade-offs table with Conflict, Lower Priority, Higher Priority, and Resolution columns
**Target Section:** ### Trade-offs (subsection under Decision-Making Framework)
**Validation Heuristics:**
- ✅ Has subsection "### Trade-offs" under Decision-Making Framework with table (Conflict, Lower Priority, Higher Priority, Resolution), 3+ conflicts using framework hierarchy
**Auto-Discovery:**
- None needed (universal trade-offs)
<!-- QUESTION_END: 3 -->
---
<!-- QUESTION_START: 4 -->
### Question 4: What are common anti-patterns to avoid?
**Expected Answer:** List of anti-patterns across principles
**Target Section:** ## Anti-Patterns to Avoid
**Validation Heuristics:**
- ✅ Has section "## Anti-Patterns to Avoid" with 5+ anti-patterns, >20 words
**Auto-Discovery:**
- None needed (universal anti-patterns)
<!-- QUESTION_END: 4 -->
---
<!-- QUESTION_START: 5 -->
### Question 5: How to verify principles compliance?
**Expected Answer:** Verification checklist with 8 items
**Target Section:** ## Verification Checklist
**Validation Heuristics:**
- ✅ Has section "## Verification Checklist" with 8-item checklist (- [ ] format) covering all 8 core principles
**Auto-Discovery:**
- None needed (universal checklist)
<!-- QUESTION_END: 5 -->
---
<!-- QUESTION_START: 6 -->
### Question 6: When should principles be updated?
**Expected Answer:** Update triggers + verification
**Target Section:** ## Maintenance
**Validation Heuristics:**
- ✅ Has section "## Maintenance" with "Update Triggers" and "Verification" subsections
**Auto-Discovery:**
- None needed (standard maintenance section)
<!-- QUESTION_END: 6 -->
---
**Overall File Validation:**
- ✅ Has SCOPE tag in first 10 lines
- ✅ File size > 100 lines (reduced from 300+ due to table format + removed domain-specific principles)
- ✅ All 8 core principles present (Standards First, YAGNI, KISS, DRY, Consumer-First Design, No Legacy Code, Documentation-as-Code, Security by Design)
**MCP Ref Hints:**
- Research: "YAGNI principle examples" (if user wants deeper explanation)
- Research: "DRY principle best practices" (if user wants industry context)
<!-- DOCUMENT_END: docs/principles.md -->
---
**Version:** 4.0.0 (MAJOR: Added Table of Contents and programmatic markers for context management)
**Last Updated:** 2025-11-18

325
skills/ln-112-reference-docs-creator/SKILL.md Normal file
View File

@@ -0,0 +1,325 @@
---
name: ln-112-reference-docs-creator
description: Creates reference documentation structure (docs/reference/ with README, adrs/, guides/, manuals/ directories). Second worker in ln-110-documents-pipeline.
---
# Reference Documentation Creator
This skill creates the reference documentation structure: docs/reference/README.md (hub with registries for ADRs/Guides/Manuals) and empty subdirectories for storing reference materials.
## When to Use This Skill
**This skill is a WORKER** invoked by **ln-110-documents-pipeline** orchestrator.
This skill should be used directly when:
- Creating only reference documentation structure (docs/reference/)
- Setting up directories for ADRs, guides, and manuals
- NOT creating full documentation structure (use ln-110-documents-pipeline for complete setup)
## How It Works
The skill follows a 3-phase workflow: **CREATE** → **VALIDATE STRUCTURE** → **VALIDATE CONTENT**. Each phase builds on the previous, ensuring complete structure and semantic validation.
---
### Phase 1: Create Structure
**Objective**: Establish reference documentation directories and README hub.
**Process**:
**1.1 Check & create directories**:
- Check if `docs/reference/adrs/` exists → create if missing
- Check if `docs/reference/guides/` exists → create if missing
- Check if `docs/reference/manuals/` exists → create if missing
- Log for each: "✓ Created docs/reference/[name]/" or "✓ docs/reference/[name]/ already exists"
**1.2 Check & create README**:
- Check if `docs/reference/README.md` exists
- If exists:
- Skip creation
- Log: "✓ docs/reference/README.md already exists, proceeding to validation"
- If NOT exists:
- Copy template: `ln-112-reference-docs-creator/references/reference_readme_template.md` → `docs/reference/README.md`
- Replace placeholders:
- `{{VERSION}}` — "1.0.0"
- `{{DATE}}` — current date (YYYY-MM-DD)
- `{{ADR_LIST}}` — kept as placeholder (filled in Phase 3)
- `{{GUIDE_LIST}}` — kept as placeholder (filled in Phase 3)
- `{{MANUAL_LIST}}` — kept as placeholder (filled in Phase 3)
- Log: "✓ Created docs/reference/README.md from template"
**1.3 Output**:
```
docs/reference/
├── README.md # Created or existing
├── adrs/ # Empty, ready for ADRs
├── guides/ # Empty, ready for guides
└── manuals/ # Empty, ready for manuals
```
---
### Phase 2: Validate Structure
**Objective**: Ensure reference/README.md complies with structural requirements and auto-fix violations.
**Process**:
**2.1 Check SCOPE tag**:
- Read `docs/reference/README.md` (first 5 lines)
- Check for `<!-- SCOPE: ... -->` tag
- Expected: `<!-- SCOPE: Reference documentation hub (ADRs, Guides, Manuals) with links to subdirectories -->`
- If missing:
- Use Edit tool to add SCOPE tag at line 1 (after first heading)
- Track violation: `scope_tag_added = True`
**2.2 Check required sections**:
- Load expected sections from `references/questions.md`
- Required sections:
- "Architecture Decision Records (ADRs)"
- "Project Guides"
- "Package Manuals"
- For each section:
- Check if `## [Section Name]` header exists
- If missing:
- Use Edit tool to add section with placeholder:
```markdown
## [Section Name]
{{PLACEHOLDER}}
```
- Track violation: `missing_sections += 1`
**2.3 Check Maintenance section**:
- Search for `## Maintenance` header
- If missing:
- Use Edit tool to add at end of file:
```markdown
## Maintenance
**Last Updated:** [current date]
**Update Triggers:**
- New ADRs added to adrs/ directory
- New guides added to guides/ directory
- New manuals added to manuals/ directory
**Verification:**
- [ ] All ADR links in registry are valid
- [ ] All guide links in registry are valid
- [ ] All manual links in registry are valid
- [ ] Placeholders {{ADR_LIST}}, {{GUIDE_LIST}}, {{MANUAL_LIST}} synced with files
```
- Track violation: `maintenance_added = True`
**2.4 Check POSIX file endings**:
- Check if file ends with single blank line
- If missing:
- Use Edit tool to add final newline
- Track fix: `posix_fixed = True`
**2.5 Report validation**:
- Log summary:
```
✅ Structure validation complete:
- SCOPE tag: [added/present]
- Missing sections: [count] sections added
- Maintenance section: [added/present]
- POSIX endings: [fixed/compliant]
```
- If violations found: "⚠️ Auto-fixed [total] structural violations"
---
### Phase 3: Validate Content
**Objective**: Ensure each section answers its questions with meaningful content and populate registries from auto-discovery.
**Process**:
**3.1 Load validation spec**:
- Read `references/questions.md`
- Parse questions and validation heuristics for all 3 sections
**3.2 Validate sections (parametric loop)**:
Define section parameters:
```
sections = [
{
"name": "Architecture Decision Records (ADRs)",
"question": "Where are architecture decisions documented?",
"directory": "docs/reference/adrs/",
"placeholder": "{{ADR_LIST}}",
"glob_pattern": "docs/reference/adrs/*.md",
"heuristics": [
"Contains link: [ADRs](adrs/) or [adrs](adrs/)",
"Mentions 'Architecture Decision Record' or 'ADR'",
"Has placeholder {{ADR_LIST}} or actual list",
"Length > 30 words"
]
},
{
"name": "Project Guides",
"question": "Where are reusable project patterns documented?",
"directory": "docs/reference/guides/",
"placeholder": "{{GUIDE_LIST}}",
"glob_pattern": "docs/reference/guides/*.md",
"heuristics": [
"Contains link: [Guides](guides/) or [guides](guides/)",
"Has placeholder {{GUIDE_LIST}} or actual list",
"Length > 20 words"
]
},
{
"name": "Package Manuals",
"question": "Where are third-party package references documented?",
"directory": "docs/reference/manuals/",
"placeholder": "{{MANUAL_LIST}}",
"glob_pattern": "docs/reference/manuals/*.md",
"heuristics": [
"Contains link: [Manuals](manuals/) or [manuals](manuals/)",
"Has placeholder {{MANUAL_LIST}} or actual list",
"Length > 20 words"
]
}
]
```
For each section in sections:
1. **Read section content**:
- Extract section from reference/README.md
2. **Check if content answers question**:
- Apply validation heuristics
- If ANY heuristic passes → content valid, skip to next section
- If ALL fail → content invalid, continue
3. **Auto-discovery** (if content invalid or placeholder present):
- Scan directory using Glob tool (section.glob_pattern)
- If files found:
- Extract filenames
- Generate dynamic list:
```markdown
- [ADR-001: Frontend Framework](adrs/adr-001-frontend-framework.md)
- [02-Repository Pattern](guides/02-repository-pattern.md)
- [Axios 1.6](manuals/axios-1.6.md)
```
- Use Edit tool to replace placeholder with generated list
- Track change: `sections_populated += 1`
- If NO files:
- Keep placeholder as-is
- Track: `placeholders_kept += 1`
4. **Skip external API calls**:
- Do NOT use MCP Ref search (template already has format examples)
**3.3 Report content validation**:
- Log summary:
```
✅ Content validation complete:
- Sections checked: 3
- Populated from auto-discovery: [count]
- Placeholders kept (no files): [count]
- Already valid: [count]
```
---
## Complete Output Structure
```
docs/
└── reference/
├── README.md # Reference hub with registries
├── adrs/ # Empty or with ADR files
├── guides/ # Empty or with guide files
└── manuals/ # Empty or with manual files
```
---
## Reference Files Used
### Templates
**Reference README Template**:
- `references/reference_readme_template.md` (v2.0.0) - Reference hub with:
- SCOPE tags (reference documentation ONLY)
- Three registry sections with placeholders
- Maintenance section
**Validation Specification**:
- `references/questions.md` (v1.0) - Question-driven validation:
- Questions each section must answer
- Validation heuristics
- Auto-discovery hints
---
## Best Practices
- **No premature validation**: Phase 1 creates structure, Phase 2 validates it (no duplicate checks)
- **Parametric validation**: Phase 3 uses loop for 3 sections (no code duplication)
- **Auto-discovery first**: Scan actual files before external API calls
- **Idempotent**: ✅ Can run multiple times safely (checks existence before creation)
- **Separation of concerns**: CREATE → VALIDATE STRUCTURE → VALIDATE CONTENT
---
## Prerequisites
**Invoked by**: ln-110-documents-pipeline orchestrator
**Requires**:
- `docs/` directory (created by ln-111-root-docs-creator)
**Creates**:
- `docs/reference/` directory structure with README hub
- Validated structure and content (auto-discovery from existing files)
---
## Definition of Done
Before completing work, verify ALL checkpoints:
**✅ Structure Created:**
- [ ] `docs/reference/` directory exists
- [ ] `docs/reference/adrs/` directory exists
- [ ] `docs/reference/guides/` directory exists
- [ ] `docs/reference/manuals/` directory exists
- [ ] `docs/reference/README.md` exists (created or existing)
**✅ Structure Validated:**
- [ ] SCOPE tag present in first 5 lines
- [ ] Three registry sections present (ADRs, Guides, Manuals)
- [ ] Maintenance section present at end
- [ ] POSIX file endings compliant
**✅ Content Validated:**
- [ ] All sections checked against questions.md
- [ ] Placeholders populated from auto-discovery OR kept if no files
- [ ] No validation heuristic failures
**✅ Reporting:**
- [ ] Phase 1 logged: creation summary
- [ ] Phase 2 logged: structural fixes (if any)
- [ ] Phase 3 logged: content updates (if any)
---
## Technical Details
**Standards**:
- Michael Nygard's ADR Format (7 sections)
- ISO/IEC/IEEE 29148:2018 (Documentation standards)
**Language**: English only
---
**Version:** 7.1.0 (MINOR: Workflow optimization - merged Phase 1+2 CREATE, removed redundant Phase 2 Step 3 verification, removed Phase 3.4 project-specific standards check, parametrized Phase 4 content validation. No functionality change, pure refactoring for clarity and efficiency.)
**Last Updated:** 2025-11-18

98
skills/ln-112-reference-docs-creator/diagram.html Normal file
View File

@@ -0,0 +1,98 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>ln-112-reference-docs-creator - State Diagram</title>
<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
<link rel="stylesheet" href="../shared/css/diagram.css">
</head>
<body>
<div class="container">
<header>
<h1>📚 ln-112-reference-docs-creator</h1>
<p class="subtitle">Reference Documentation Creator - State Diagram</p>
</header>
<div class="info-box">
<h3>📋 Workflow Overview</h3>
<ul>
<li><strong>Purpose:</strong> Create reference documentation structure (adrs/, guides/, manuals/) + README hub</li>
<li><strong>Worker for:</strong> ln-110-documents-pipeline orchestrator</li>
<li><strong>Phases:</strong> 4 phases (Phase 1+2 CREATE merged → Phase 3 Structure Validation → Phase 4 Content Validation)</li>
<li><strong>Optimization:</strong> Merged Phase 1+2 CREATE, removed redundant verifications, parametrized validation</li>
<li><strong>Output:</strong> Empty structure with registries ready for content creation</li>
</ul>
</div>
<div class="legend">
<div class="legend-item">
<div class="legend-color color-action"></div>
<span>Creation Action</span>
</div>
<div class="legend-item">
<div class="legend-color color-validation"></div>
<span>Validation</span>
</div>
<div class="legend-item">
<div class="legend-color color-success"></div>
<span>Success State</span>
</div>
</div>
<div class="diagram-container">
<div class="mermaid">
graph TD
Start([Start: Reference Docs Creation]) --> Phase1[Phase 1+2: Create Structure merged<br/>Create dirs + README + ADR template]
Phase1 --> CreateAll[Create subdirectories adrs/, guides/, manuals/<br/>+ README.md + _template.md]
CreateAll --> ReplaceVars[Replace placeholders:<br/>DATE, registries]
ReplaceVars --> Phase3[Phase 3: Structure Validation<br/>Verify dirs, SCOPE tags, registries]
Phase3 --> Phase4[Phase 4: Content Validation<br/>Parametric validation with questions.md]
Phase4 --> Notify[Notify: Reference structure<br/>created + validated]
Notify --> End([End: ✓ Reference structure ready])
%% Styling
classDef action fill:#C8E6C9,stroke:#388E3C,stroke-width:2px
classDef validation fill:#FFF9C4,stroke:#F57C00,stroke-width:2px
classDef success fill:#B3E5FC,stroke:#0277BD,stroke-width:2px
class Phase1,CreateAll,ReplaceVars action
class Phase3,Phase4 validation
class Notify action
class End success
</div>
</div>
<div class="info-box">
<h3>🔑 Key Features</h3>
<ul>
<li><strong>Second Worker:</strong> Creates reference documentation structure after root docs</li>
<li><strong>Structure Only:</strong> Creates directories and registries, NOT content</li>
<li><strong>ADR Template:</strong> Copies Michael Nygard's 7-section ADR template</li>
<li><strong>Validation:</strong> Parametric content validation (Phase 4) with project-specific standards removal</li>
</ul>
</div>
<footer>
<p>Generated for ln-112-reference-docs-creator skill | Version 7.1.0</p>
<p>Diagram format: Mermaid.js | Last updated: 2025-11-18</p>
</footer>
</div>
<script>
mermaid.initialize({
startOnLoad: true,
theme: 'default',
flowchart: {
useMaxWidth: true,
htmlLabels: true,
curve: 'basis'
}
});
</script>
</body>
</html>

119
skills/ln-112-reference-docs-creator/references/questions.md Normal file
View File

@@ -0,0 +1,119 @@
# Reference Documentation Questions
**Purpose:** Define what each section of reference documentation should answer.
**Format:** Question → Expected Content → Validation Heuristics → Auto-Discovery Hints → MCP Ref Hints
---
## Table of Contents
| Document | Questions | Auto-Discovery | Priority | Line |
|----------|-----------|----------------|----------|------|
| [docs/reference/README.md](#docsreferencereadmemd) | 3 | High | High | L23 |
**Priority Legend:**
- **Critical:** Must answer all questions
- **High:** Strongly recommended
- **Medium:** Optional (can use template defaults)
**Auto-Discovery Legend:**
- **None:** No auto-discovery needed (use template as-is)
- **Low:** 1-2 questions need auto-discovery
- **High:** All questions need auto-discovery
---
<!-- DOCUMENT_START: docs/reference/README.md -->
## docs/reference/README.md
**File:** docs/reference/README.md (reference documentation hub)
**Target Sections:** Architecture Decision Records (ADRs), Project Guides, Package Manuals
**Rules for this document:**
- Hub file for reference documentation subdirectories
- Must link to adrs/, guides/, manuals/ directories
- Auto-discovery of existing files in each directory
---
<!-- QUESTION_START: 1 -->
### Question 1: Where are architecture decisions documented?
**Expected Answer:** Link to adrs/ directory, ADR format description (Nygard template), list of existing ADRs or placeholder
**Target Section:** ## Architecture Decision Records (ADRs)
**Validation Heuristics:**
- ✅ Contains link: `[ADRs](adrs/)` or `[adrs](adrs/)`
- ✅ Mentions "Architecture Decision Record" or "ADR"
- ✅ Has placeholder `{{ADR_LIST}}` or actual ADR list
- ✅ Length > 30 words
**Auto-Discovery:**
- Scan `docs/reference/adrs/` for *.md files
- Generate list dynamically from filenames
- Example: `adr-001-frontend-framework.md` → "ADR-001: Use React+Next.js"
**MCP Ref Hints:**
- Research: "Michael Nygard ADR format" (if no ADRs exist and need to explain format)
- Extract: ADR template structure (Context, Decision, Status, Consequences)
<!-- QUESTION_END: 1 -->
---
<!-- QUESTION_START: 2 -->
### Question 2: Where are reusable project patterns documented?
**Expected Answer:** Link to guides/ directory, description of guide purpose (reusable patterns, how-tos), list of existing guides or placeholder
**Target Section:** ## Project Guides
**Validation Heuristics:**
- ✅ Contains link: `[Guides](guides/)` or `[guides](guides/)`
- ✅ Mentions "patterns" or "guides" or "how-to"
- ✅ Has placeholder `{{GUIDE_LIST}}` or actual guide list
- ✅ Length > 20 words
**Auto-Discovery:**
- Scan `docs/reference/guides/` for *.md files
- Generate list dynamically from filenames
- Example: `authentication-flow.md` → "Authentication Flow Guide"
**MCP Ref Hints:**
- N/A (guides are project-specific)
<!-- QUESTION_END: 2 -->
---
<!-- QUESTION_START: 3 -->
### Question 3: Where are third-party package references documented?
**Expected Answer:** Link to manuals/ directory, description of manual purpose (package API references, version-specific), list of existing manuals or placeholder
**Target Section:** ## Package Manuals
**Validation Heuristics:**
- ✅ Contains link: `[Manuals](manuals/)` or `[manuals](manuals/)`
- ✅ Mentions "packages" or "API reference" or "manuals"
- ✅ Has placeholder `{{MANUAL_LIST}}` or actual manual list
- ✅ Length > 20 words
**Auto-Discovery:**
- Scan `docs/reference/manuals/` for *.md files
- Generate list dynamically from filenames
- Example: `axios-1.6.md` → "Axios 1.6 API Manual"
**MCP Ref Hints:**
- N/A (manuals are package-specific, created by ln-323-manual-creator)
<!-- QUESTION_END: 3 -->
---
**Overall File Validation:**
- ✅ Has links to all 3 subdirectories (adrs/, guides/, manuals/)
- ✅ Total length > 60 words
<!-- DOCUMENT_END: docs/reference/README.md -->
---
**Version:** 2.0.0 (MAJOR: Added Table of Contents and programmatic markers for context management)
**Last Updated:** 2025-11-18

63
skills/ln-112-reference-docs-creator/references/reference_readme_template.md Normal file
View File

@@ -0,0 +1,63 @@
# Reference Documentation
**Version:** {{VERSION}}
**Last Updated:** {{DATE}}
<!-- SCOPE: Reference documentation hub (ADRs, Guides, Manuals) with links to subdirectories -->
<!-- DO NOT add here: ADR/Guide/Manual content → specific files, Project details → project/README.md -->
---
## Overview
This directory contains reusable knowledge base and architecture decisions:
- **Architecture Decision Records (ADRs)** - Key technical decisions
- **Project Guides** - Reusable patterns and best practices
- **Package Manuals** - API reference for external libraries
---
## Architecture Decision Records (ADRs)
<!-- Example: [ADR-001: Use React+Next.js](adrs/adr-001-frontend-framework.md) | Accepted | 2024-10-15 -->
{{ADR_LIST}}
---
## Project Guides
<!-- Example: [01-Repository Pattern](guides/01-repository-pattern.md) | 2024-11-10 -->
{{GUIDE_LIST}}
---
## Package Manuals
<!-- Example: [Axios 1.6](manuals/axios-1.6.md) | 2024-10-20 -->
{{MANUAL_LIST}}
---
## Maintenance
**Last Updated:** {{DATE}}
**Update Triggers:**
- New ADRs added to adrs/ directory
- New guides added to guides/ directory
- New manuals added to manuals/ directory
**Verification:**
- [ ] All ADR links in registry are valid
- [ ] All guide links in registry are valid
- [ ] All manual links in registry are valid
- [ ] Placeholders {{ADR_LIST}}, {{GUIDE_LIST}}, {{MANUAL_LIST}} synced with files
---
**Template Version:** 2.0.0
**Template Last Updated:** {{DATE}}

509
skills/ln-113-tasks-docs-creator/SKILL.md Normal file
View File

@@ -0,0 +1,509 @@
---
name: ln-113-tasks-docs-creator
description: Creates task management documentation (docs/tasks/README.md + kanban_board.md). Third worker in ln-110-documents-pipeline. Sets up Linear integration and task tracking rules.
---
# Tasks Documentation Creator
This skill creates task management documentation: docs/tasks/README.md (task management system rules) and docs/tasks/kanban_board.md (Linear integration with Epic Story Counters).
## When to Use This Skill
**This skill is a WORKER** invoked by **ln-110-documents-pipeline** orchestrator OR used standalone.
Use this skill when:
- Creating task management documentation (docs/tasks/)
- Setting up Linear integration and kanban board
- Validating existing task documentation structure and content
- Configuring Linear team settings (Team Name, UUID, Key)
**Part of workflow**: ln-110-documents-pipeline → ln-111-root-docs-creator → ln-112-reference-docs-creator → **ln-113-tasks-docs-creator** → ln-114-project-docs-creator → ln-115-presentation-creator
## How It Works
The skill follows a **3-phase workflow**: CREATE → VALIDATE STRUCTURE → VALIDATE CONTENT.
**Phase 1: CREATE** - Create tasks/README.md from template with SCOPE tags, workflow rules, Linear integration
**Phase 2: VALIDATE STRUCTURE** - Auto-fix structural violations (SCOPE tags, sections, Maintenance, POSIX)
**Phase 3: VALIDATE CONTENT** - Validate semantic content + special Linear Configuration handling (placeholder detection, UUID/Team Key validation, interactive user prompts)
---
## Phase 1: Create tasks/README.md
**Objective**: Create task management system documentation from template.
**When to execute**: Always (first phase)
**Process**:
1. **Check if tasks/README.md exists**:
- Use Glob tool: `pattern: "docs/tasks/README.md"`
- If file exists:
- Skip creation
- Log: `✓ docs/tasks/README.md already exists (preserved)`
- Proceed to Phase 2
- If NOT exists:
- Continue to step 2
2. **Create tasks directory**:
- Create the `docs/tasks/` directory if it doesn't exist
3. **Create tasks/README.md from template**:
- Copy template: `references/tasks_readme_template.md` (v2.0.0) → `docs/tasks/README.md`
- Replace placeholders:
- `{{DATE}}` → current date (YYYY-MM-DD)
- Template contains:
- SCOPE tags: `<!-- SCOPE: Task tracking system workflow and rules ONLY -->`
- Story-Level Test Task Pattern
- Kanban Board Structure (Epic Grouping Pattern)
- Linear Integration (MCP methods)
- Maintenance section
4. **Notify user**:
- If created: `✓ Created docs/tasks/README.md with task management rules`
- If skipped: `✓ docs/tasks/README.md already exists (preserved)`
**Output**: docs/tasks/README.md (created or existing)
---
## Phase 2: Validate Structure
**Objective**: Ensure tasks/README.md and kanban_board.md comply with structural requirements. Auto-fix violations.
**When to execute**: After Phase 1 completes (files exist or created)
**Process**:
### 2.1 Validate SCOPE tags
**Files to check**: docs/tasks/README.md, docs/tasks/kanban_board.md (if exists)
For each file:
1. Read first 5 lines
2. Check for `<!-- SCOPE: ... -->` tag
3. Expected values:
- tasks/README.md: `<!-- SCOPE: Task tracking system workflow and rules ONLY -->`
- kanban_board.md: `<!-- SCOPE: Quick navigation to active tasks in Linear -->`
4. **If missing:**
- Use Edit tool to add SCOPE tag after first heading
- Log: `⚠ Auto-fixed: Added missing SCOPE tag to {filename}`
### 2.2 Validate required sections
**Load validation spec**:
- Read `references/questions.md`
- Extract section names from questions
**For tasks/README.md**:
- Required sections (from questions.md):
- "Linear Integration" OR "Core Concepts" (Linear MCP methods)
- "Task Workflow" OR "Critical Rules" (state transitions)
- "Task Templates" (template references)
- For each section:
- Check if section header exists (case-insensitive)
- **If missing:**
- Use Edit tool to add section with placeholder content
- Log: `⚠ Auto-fixed: Added missing section '{section}' to tasks/README.md`
**For kanban_board.md** (if exists):
- Required sections:
- "Linear Configuration" (Team Name, UUID, Key)
- "Work in Progress" OR "Epic Tracking" (Kanban sections)
- For each section:
- Check if section header exists
- **If missing:**
- Use Edit tool to add section with placeholder
- Log: `⚠ Auto-fixed: Added missing section '{section}' to kanban_board.md`
### 2.3 Validate Maintenance section
**Files to check**: docs/tasks/README.md, docs/tasks/kanban_board.md (if exists)
For each file:
1. Search for `## Maintenance` header in last 20 lines
2. **If missing:**
- Use Edit tool to add at end of file:
```markdown
## Maintenance
**Update Triggers:**
- When Linear workflow changes
- When task templates are added/modified
- When label taxonomy changes
**Last Updated:** {current_date}
```
- Log: `⚠ Auto-fixed: Added Maintenance section to {filename}`
### 2.4 Validate POSIX line endings
**Files to check**: docs/tasks/README.md, docs/tasks/kanban_board.md (if exists)
For each file:
1. Check if file ends with single newline character
2. **If missing:**
- Use Edit tool to add final newline
- Log: `⚠ Auto-fixed: Added POSIX newline to {filename}`
### 2.5 Report validation summary
Log summary:
```
✓ Structure validation completed:
tasks/README.md:
- SCOPE tag: [added/present]
- Required sections: [count] sections [added/present]
- Maintenance section: [added/present]
- POSIX endings: [fixed/compliant]
kanban_board.md:
- SCOPE tag: [added/present/skipped - file not exists]
- Required sections: [count] sections [added/present/skipped]
- Maintenance section: [added/present/skipped]
- POSIX endings: [fixed/compliant/skipped]
```
If violations found: `⚠ Auto-fixed {total} structural violations`
**Output**: Structurally valid task management documentation
---
## Phase 3: Validate Content
**Objective**: Ensure each section answers its validation questions with meaningful content. Special handling for Linear Configuration (placeholder detection, user prompts, UUID/Team Key validation).
**When to execute**: After Phase 2 completes (structure valid, auto-fixes applied)
**Process**:
### 3.1 Load validation spec
1. Read `references/questions.md`
2. Parse document sections and questions
3. Extract validation heuristics for each section
### 3.2 Validate kanban_board.md → Linear Configuration (Special Handling)
**Question**: "What is the Linear team configuration?"
**Step 3.2.1: Check if kanban_board.md exists**:
- Use Glob tool: `pattern: "docs/tasks/kanban_board.md"`
- If NOT exists:
- Log: `ℹ kanban_board.md not found - skipping Linear Configuration validation`
- Skip to Step 3.3
- If exists:
- Continue to Step 3.2.2
**Step 3.2.2: Read Linear Configuration section**:
- Read `docs/tasks/kanban_board.md`
- Locate `## Linear Configuration` section
- Extract Team Name, Team UUID, Team Key values
**Step 3.2.3: Placeholder Detection**:
Check for placeholders:
```
Pattern: [TEAM_NAME], [TEAM_UUID], [TEAM_KEY]
If ANY placeholder present → Interactive Setup Mode
If NO placeholders present → Validation Mode
```
**Interactive Setup Mode** (if placeholders detected):
1. **Prompt user for Team Name**:
- Question: "What is your Linear Team Name?"
- Validation: Non-empty string
- Example: "My Project Team"
2. **Prompt user for Team UUID**:
- Question: "What is your Linear Team UUID?"
- Format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
- Validation Regex: `/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/`
- **If invalid:**
- Show error: "Invalid UUID format. Expected: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (lowercase hex)"
- Re-prompt user
- Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
3. **Prompt user for Team Key**:
- Question: "What is your Linear Team Key (2-4 uppercase letters)?"
- Format: 2-4 uppercase letters
- Validation Regex: `/^[A-Z]{2,4}$/`
- **If invalid:**
- Show error: "Invalid Team Key format. Expected: 2-4 uppercase letters (e.g., PROJ, WEB, API)"
- Re-prompt user
- Example: "PROJ"
4. **Replace placeholders**:
- Use Edit tool to replace in kanban_board.md:
- `[TEAM_NAME]` → `{user_team_name}`
- `[TEAM_UUID]` → `{user_team_uuid}`
- `[TEAM_KEY]` → `{user_team_key}`
- `[WORKSPACE_URL]` → `https://linear.app/{workspace_slug}` (if placeholder exists)
5. **Set initial counters** (if table exists):
- Set "Next Epic Number" → 1
- Set "Next Story Number" → 1
6. **Update Last Updated date**:
- Replace `[YYYY-MM-DD]` → `{current_date}` in Maintenance section
7. **Save updated kanban_board.md**
8. **Log success**:
```
✓ Linear configuration updated:
- Team Name: {user_team_name}
- Team UUID: {user_team_uuid}
- Team Key: {user_team_key}
- Next Epic Number: 1
- Next Story Number: 1
```
**Validation Mode** (if real values present, no placeholders):
1. **Extract existing values**:
- Extract Team UUID from line matching: `Team UUID: {value}` or in table
- Extract Team Key from line matching: `Team Key: {value}` or in table
2. **Validate formats**:
- UUID: `/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/`
- Team Key: `/^[A-Z]{2,4}$/`
3. **If validation fails**:
```
⚠ Invalid format detected in Linear Configuration:
- Team UUID: {uuid} (expected: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
- Team Key: {key} (expected: 2-4 uppercase letters)
Fix manually or re-run skill to replace with correct values.
```
- Mark as invalid but continue (don't block)
4. **If validation passes**:
```
✓ Linear Configuration valid (Team: {name}, UUID: {uuid}, Key: {key})
```
### 3.3 Validate tasks/README.md sections
**Parametric loop for 3 questions** (from questions.md):
For each question in:
1. "How is Linear integrated into the task management system?"
2. "What are the task state transitions and review criteria?"
3. "What task templates are available and how to use them?"
**Validation process**:
1. Extract validation heuristics from questions.md
2. Read corresponding section content from tasks/README.md
3. Check if **ANY** heuristic passes:
- Contains keyword X → pass
- Has pattern Y → pass
- Length > N words → pass
4. If ANY passes → Section valid
5. If NONE passes → Log warning: `⚠ Section may be incomplete: {section_name}`
**Example validation (Question 1: Linear Integration)**:
```
Heuristics:
- Contains "Linear" or "MCP" → pass
- Mentions team ID or UUID → pass
- Has workflow states (Backlog, Todo, In Progress) → pass
- Length > 100 words → pass
Check content:
- ✓ Contains "Linear" → PASS
→ Section valid
```
**No auto-discovery needed** (workflow is standardized in template)
### 3.4 Validate kanban_board.md → Epic Tracking
**Question**: "Are Epics being tracked in the board?"
**If kanban_board.md exists**:
**Validation heuristics**:
```
- Has "Epic" or "Epics Overview" section header → pass
- Has table with columns: Epic, Name, Status, Progress → pass
- OR has placeholder: "No active epics" → pass
- Length > 20 words → pass
```
**Action**:
1. Read Epic Tracking or Epics Overview section
2. Check if ANY heuristic passes
3. If passes → valid
4. If none pass → log warning: `⚠ Epic Tracking section may be incomplete`
**If kanban_board.md does NOT exist**:
- Skip validation
- Log: `ℹ Epic Tracking validation skipped (kanban_board.md not found)`
### 3.5 Report content validation summary
Log summary:
```
✓ Content validation completed:
tasks/README.md:
- ✓ Linear Integration: valid (contains "Linear", "MCP", workflow states)
- ✓ Task Workflow: valid (contains state transitions)
- ✓ Task Templates: valid (contains template references)
kanban_board.md:
- ✓ Linear Configuration: {status} (Team: {name}, UUID: {uuid}, Key: {key})
- ✓ Epic Tracking: valid (table present or placeholder)
```
**Output**: Validated and potentially updated task management documentation with Linear configuration
---
## Complete Output Structure
```
docs/
└── tasks/
├── README.md # Task management system rules
└── kanban_board.md # Linear integration (optional, created manually or by other skills)
```
**Note**: Kanban board updated by ln-311-task-creator, ln-312-task-replanner, ln-330-story-executor (Epic Grouping logic).
---
## Reference Files Used
### Templates
**Tasks README Template**:
- `references/tasks_readme_template.md` (v2.0.0) - Task management system rules with:
- SCOPE tags (task management ONLY)
- Story-Level Test Task Pattern (tests in final Story task, NOT scattered)
- Kanban Board Structure (Epic Grouping Pattern with Status → Epic → Story → Tasks hierarchy)
- Linear Integration (MCP methods: create_project, create_issue, update_issue, list_issues)
- Maintenance section (Update Triggers, Verification, Last Updated)
**Kanban Board Template**:
- `references/kanban_board_template.md` (v3.0.0) - Linear integration template with:
- Linear Configuration table (Team Name, UUID, Key, Workspace URL)
- Epic Story Counters table (Next Epic Number, Story counters per Epic)
- Kanban sections: Backlog, Todo (✅ APPROVED), In Progress, To Review, To Rework, Done (Last 5 tasks), Postponed
- Epic Grouping Pattern format (Epic header → 📖 Story → Task with indentation)
- Placeholders for Epic/Story/Task entries
### Validation Specification
**questions.md**:
- `references/questions.md` (v1.0) - Validation questions for task management documentation:
- 5 sections (3 for tasks/README.md, 2 for kanban_board.md)
- Question format: Question → Expected Content → Validation Heuristics → Auto-Discovery Hints → MCP Ref Hints
- Special handling section for Linear Configuration (placeholder detection, UUID/Team Key validation)
---
## Best Practices
- **Story-Level Test Task Pattern**: Tests consolidated in final Story task, NOT scattered across implementation tasks
- **Epic Grouping Pattern**: Epic context always visible, 0/2/4 space indentation (Epic → Story → Tasks)
- **Linear MCP**: All task operations use Linear MCP methods (create_project, create_issue, update_issue)
- **SCOPE Tags**: Include in first 3-5 lines of all documentation files
- **Idempotent**: Can be invoked multiple times - checks file existence, preserves existing files, re-validates on each run
---
## Prerequisites
**Orchestrator**: ln-110-documents-pipeline (invokes this worker in Phase 3, Step 3.3)
**Standalone usage**: Can also be invoked directly for:
- Creating only task management documentation
- Re-validating existing task documentation
- Setting up Linear Configuration interactively
**Idempotent**: Yes - can be invoked multiple times without side effects. The skill:
- Checks file existence before creation (preserves existing files)
- Re-validates structure and content on each run
- Auto-fixes structural violations (SCOPE tags, sections, Maintenance, POSIX)
- Updates Linear Configuration if placeholders detected
**Dependencies**: None (standalone worker)
---
## Definition of Done
Before completing work, verify ALL checkpoints:
### Phase 1: CREATE
**✅ tasks/README.md:**
- [ ] `docs/tasks/` directory created (if didn't exist)
- [ ] `docs/tasks/README.md` created from template (if didn't exist) OR preserved (if existed)
- [ ] All `{{DATE}}` placeholders replaced with current date
- [ ] Template contains SCOPE tags, Story-Level Test Task Pattern, Kanban Board Structure, Linear Integration, Maintenance section
- [ ] User notified: created OR preserved
### Phase 2: VALIDATE STRUCTURE
**✅ tasks/README.md:**
- [ ] SCOPE tag present in first 5 lines OR auto-fixed
- [ ] Required sections present (Linear Integration/Core Concepts, Task Workflow/Critical Rules, Task Templates) OR auto-fixed
- [ ] Maintenance section present at end OR auto-fixed
- [ ] POSIX line ending present OR auto-fixed
- [ ] Validation summary logged
**✅ kanban_board.md (if exists):**
- [ ] SCOPE tag present OR auto-fixed
- [ ] Required sections present (Linear Configuration, Work in Progress/Epic Tracking) OR auto-fixed
- [ ] Maintenance section present OR auto-fixed
- [ ] POSIX line ending present OR auto-fixed
- [ ] Validation summary logged
### Phase 3: VALIDATE CONTENT
**✅ tasks/README.md:**
- [ ] Linear Integration section validated (contains "Linear" OR "MCP" OR team ID OR workflow states OR length > 100 words)
- [ ] Task Workflow section validated (contains workflow states OR review criteria OR length > 60 words)
- [ ] Task Templates section validated (contains "template" OR Epic/Story/Task OR links OR length > 40 words)
- [ ] Validation summary logged
**✅ kanban_board.md (if exists):**
- [ ] Linear Configuration section validated:
- [ ] If placeholders detected ([TEAM_NAME], [TEAM_UUID], [TEAM_KEY]):
- [ ] User prompted for Team Name (non-empty validation)
- [ ] User prompted for Team UUID (regex validation: `/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/`)
- [ ] User prompted for Team Key (regex validation: `/^[A-Z]{2,4}$/`)
- [ ] Placeholders replaced with user input
- [ ] Next Epic Number set to 1
- [ ] Next Story Number set to 1
- [ ] Last Updated date updated
- [ ] If real values present:
- [ ] Team UUID format validated
- [ ] Team Key format validated
- [ ] Validation result logged (valid OR invalid with warning)
- [ ] Epic Tracking section validated (has "Epic" header OR table OR placeholder OR length > 20 words)
- [ ] Validation summary logged
**✅ Overall:**
- [ ] Summary message displayed: "✓ Task management documentation validated (3-phase complete)"
- [ ] User informed about any auto-fixes applied
- [ ] User informed about Linear Configuration status (if applicable)
**Output:** docs/tasks/README.md + optionally kanban_board.md (validated, auto-fixed where needed, Linear Configuration set up if placeholders found)
---
## Technical Details
**Standards**: Story-Level Test Task Pattern, Epic Grouping Pattern (Status → Epic → Story → Tasks), Linear MCP integration
**Language**: English only
---
**Version:** 7.0.0 (MAJOR: Added Phase 2/3 validation. Merged CREATE+VALIDATE into unified worker. Special Linear Configuration handling with UUID/Team Key validation, user prompts for placeholders. Idempotent.)
**Last Updated:** 2025-11-18

123
skills/ln-113-tasks-docs-creator/diagram.html Normal file
View File

@@ -0,0 +1,123 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>ln-113-tasks-docs-creator - State Diagram</title>
<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
<link rel="stylesheet" href="../shared/css/diagram.css">
</head>
<body>
<div class="container">
<header>
<h1>📋 ln-113-tasks-docs-creator</h1>
<p class="subtitle">Tasks Documentation Creator - State Diagram</p>
</header>
<div class="info-box">
<h3>📋 Workflow Overview</h3>
<ul>
<li><strong>Purpose:</strong> Create task management documentation (docs/tasks/README.md + kanban_board.md)</li>
<li><strong>Worker for:</strong> ln-110-documents-pipeline orchestrator</li>
<li><strong>Phases:</strong> 3 phases (Phase 1 CREATE → Phase 2 Structure Validation → Phase 3 Content Validation)</li>
<li><strong>Linear Integration:</strong> Special handling for Linear Configuration (UUID/Team Key validation, placeholder detection)</li>
<li><strong>Auto-Discovery:</strong> Epic Story Counters for automatic team configuration</li>
</ul>
</div>
<div class="legend">
<div class="legend-item">
<div class="legend-color color-action"></div>
<span>Creation Action</span>
</div>
<div class="legend-item">
<div class="legend-color color-validation"></div>
<span>Validation</span>
</div>
<div class="legend-item">
<div class="legend-color color-decision"></div>
<span>Conditional Check</span>
</div>
</div>
<div class="diagram-container">
<div class="mermaid">
graph TD
Start([Start: Tasks Docs Creation]) --> Phase1[Phase 1: CREATE tasks/README.md]
Phase1 --> CheckExists{README.md<br/>exists?}
CheckExists -->|Yes| Preserved[Preserve existing<br/>README.md]
CheckExists -->|No| CreateReadme[Create from template<br/>+ replace DATE placeholder]
Preserved --> Phase2
CreateReadme --> Phase2
Phase2[Phase 2: Structure Validation<br/>Auto-fix SCOPE tags, sections, Maintenance]
Phase2 --> AutoFix[Auto-fix violations:<br/>SCOPE tags, required sections,<br/>Maintenance, POSIX endings]
AutoFix --> Phase3[Phase 3: Content Validation<br/>Semantic validation + Linear Configuration]
Phase3 --> ValidateReadme[Validate tasks/README.md sections:<br/>Linear Integration, Task Workflow, Templates]
Phase3 --> CheckKanban{kanban_board.md<br/>exists?}
CheckKanban -->|No| Summary
CheckKanban -->|Yes| LinearConfig[Linear Configuration<br/>Special Handling]
LinearConfig --> PlaceholderCheck{Has placeholders<br/>[TEAM_NAME/UUID/KEY]?}
PlaceholderCheck -->|Yes| InteractiveSetup[Interactive Setup Mode<br/>User prompts + validation:<br/>UUID regex, Team Key regex]
PlaceholderCheck -->|No| ValidationMode[Validation Mode<br/>Check UUID/Team Key formats]
InteractiveSetup --> UpdateConfig[Replace placeholders<br/>+ Set Epic/Story counters to 1]
ValidationMode --> EpicTracking
UpdateConfig --> EpicTracking[Validate Epic Tracking section]
EpicTracking --> Summary
ValidateReadme --> Summary[Notify: Task documentation<br/>validated (3-phase complete)]
Summary --> End([End: ✓ Tasks docs created + validated])
%% Styling
classDef action fill:#C8E6C9,stroke:#388E3C,stroke-width:2px
classDef validation fill:#FFF9C4,stroke:#F57C00,stroke-width:2px
classDef decision fill:#FFE0B2,stroke:#E64A19,stroke-width:2px
class Phase1,CreateReadme,Preserved,AutoFix,InteractiveSetup,UpdateConfig,Summary action
class Phase2,Phase3,ValidateReadme,LinearConfig,ValidationMode,EpicTracking validation
class CheckExists,CheckKanban,PlaceholderCheck decision
</div>
</div>
<div class="info-box">
<h3>🔑 Key Features</h3>
<ul>
<li><strong>Third Worker:</strong> Creates task management system after reference docs (ln-110 → ln-111 → ln-112 → ln-113)</li>
<li><strong>Story-Level Test Task Pattern:</strong> Documents test consolidation approach (tests in final Story task)</li>
<li><strong>Epic Grouping Pattern:</strong> Status → Epic → Story → Tasks hierarchy (0/2/4 space indentation)</li>
<li><strong>Linear Configuration:</strong> UUID/Team Key validation with regex, Interactive Setup Mode for placeholders</li>
<li><strong>Epic Story Counters:</strong> Auto-discovery integration (Next Epic Number, Story counters per Epic)</li>
<li><strong>Idempotent:</strong> Can be invoked multiple times - preserves existing files, re-validates on each run</li>
</ul>
</div>
<footer>
<p>Generated for ln-113-tasks-docs-creator skill | Version 7.0.0</p>
<p>Diagram format: Mermaid.js | Last updated: 2025-11-18</p>
</footer>
</div>
<script>
mermaid.initialize({
startOnLoad: true,
theme: 'default',
flowchart: {
useMaxWidth: true,
htmlLabels: true,
curve: 'basis'
}
});
</script>
</body>
</html>

170
skills/ln-113-tasks-docs-creator/references/kanban_board_template.md Normal file
View File

@@ -0,0 +1,170 @@
# Task Navigation
> **SCOPE:** Quick navigation to active tasks in Linear. Contains ONLY links and titles per Context Budget Rule. DO NOT add: task descriptions, implementation notes, or workflow rules (→ tasks/README.md).
> **Last Updated**: [YYYY-MM-DD] (Hierarchical format: Status → Epic → Story → Tasks)
---
## Linear Configuration (use MCP Linear)
**What is Linear:** Issue tracking and project management tool with workspace → initiative → project → issue hierarchy.
**Our Configuration:**
- **Workspace**: [TEAM_NAME] ([WORKSPACE_URL])
- **Team**: [TEAM_NAME] (Team Key: [TEAM_KEY])
- **Initiative**: [Your Initiative Name]
- **Projects**: Each Epic = separate Linear Project
- **Issues**: User Stories (label:user-story, parentId=null) + Tasks (parentId=StoryId)
**Key Features:**
- Custom views replicate kanban workflow (Backlog → Active → Review → Done)
- Labels for technical categorization (db, api, service, testing)
- Issue titles preserve Epic context (EP{N}_{XX}: Task Name)
- Single source of truth for all task tracking
**Detailed Guide:** See [docs/guides/25-linear-task-management.md](../guides/25-linear-task-management.md) for:
- Hierarchical structure and best practices
- Custom views, labels, and workflow patterns
- Team keyboard shortcuts and bulk actions
**Single Source of Truth for all Linear variables**
| Variable | Value | Description |
|----------|-------|-------------|
| **Team ID** | [TEAM_NAME] | Linear team name |
| **Team UUID** | [TEAM_UUID] | Team UUID for API calls |
| **Team Key** | [TEAM_KEY] | Short key for issues ([TEAM_KEY]-XX) |
| **Workspace URL** | [WORKSPACE_URL] | Linear workspace |
| **Next Epic Number** | 1 | Next available Epic number |
## Quick Access
**Views:**
- [Backlog]([WORKSPACE_URL]/team/[TEAM_KEY]/backlog)
- [Todo]([WORKSPACE_URL]/team/[TEAM_KEY])
- [Active Sprint]([WORKSPACE_URL]/team/[TEAM_KEY]/active)
- [All Issues]([WORKSPACE_URL]/team/[TEAM_KEY]/all)
---
### Epic Story Counters
| Epic | Last Story | Next Story | Last Task | Next Task |
|------|------------|------------|-----------|-----------|
| Epic 0 | - | US001 | - | EP0_01 |
| Epic 1+ | - | US001 | - | EP1_01 |
> [!NOTE]
> User Story numbering starts at US001 for each new Epic. Task numbering starts at EP{N}_01 where N is the Epic number. [TEAM_KEY]-XX numbers are auto-generated by Linear.
---
## Work in Progress
**Format:** Each status section groups tasks by Epic → Story → Tasks hierarchy. Epic headers (`**Epic N: Title**`) have no indent. Stories have 2-space indent. Tasks have 4-space indent (2 base + 2 for dash).
**Important:** Stories without tasks are ONLY allowed in Backlog/Postponed statuses with note: `_(tasks not created yet)_`
### Backlog
**Epic 0: Common Tasks**
📖 [[TEAM_KEY]-XX: US001 Example Story Title](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX)
_( tasks not created yet)_
**Epic 1: Example Feature Area**
📖 [[TEAM_KEY]-XX: US001 Another Example Story](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX)
- [[TEAM_KEY]-XX: EP1_01 Example Task](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX)
### Todo
**Epic 1: Example Feature Area**
📖 [[TEAM_KEY]-XX: US002 Approved Story Title](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX) ✅ APPROVED
- [[TEAM_KEY]-XX: EP1_02 Ready Task](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX)
- [[TEAM_KEY]-XX: EP1_03 Another Ready Task](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX)
### In Progress
**Epic 1: Example Feature Area**
📖 [[TEAM_KEY]-XX: US002 Approved Story Title](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX) ✅ APPROVED
- [[TEAM_KEY]-XX: EP1_02 Active Task](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX)
### To Review
**Epic 1: Example Feature Area**
📖 [[TEAM_KEY]-XX: US002 Approved Story Title](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX) ✅ APPROVED
- [[TEAM_KEY]-XX: EP1_02 Task Under Review](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX)
### To Rework
**Epic 1: Example Feature Area**
📖 [[TEAM_KEY]-XX: US002 Approved Story Title](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX) ✅ APPROVED
- [[TEAM_KEY]-XX: EP1_02 Task Needing Fixes](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX)
### Done (Last 5 tasks)
**Epic 0: Common Tasks**
📖 [[TEAM_KEY]-XX: US001 Completed Story](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX) ✅ DONE
- [[TEAM_KEY]-XX: EP0_01 Completed Task 1](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX)
- [[TEAM_KEY]-XX: EP0_02 Completed Task 2](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX)
**Epic 1: Example Feature Area**
📖 [[TEAM_KEY]-XX: US002 Another Completed Story](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX) ✅ DONE
- [[TEAM_KEY]-XX: EP1_01 Completed Task](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX)
### Postponed
**Epic 0: Common Tasks**
📖 [[TEAM_KEY]-XX: US003 Deferred Story](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX)
_(tasks not created yet)_
**Epic 2: Future Feature**
📖 [[TEAM_KEY]-XX: US001 Postponed Work](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX)
- [[TEAM_KEY]-XX: EP2_01 Postponed Task](https://linear.app/[workspace]/issue/[TEAM_KEY]-XX)
---
## Epics Overview
**Active:**
_No active epics yet_
**Completed:**
_No completed epics yet_
---
## Workflow Reference
| Status | Purpose |
|--------|---------|
| **Backlog** | New tasks requiring estimation and approval |
| **Postponed** | Deferred tasks for future iterations |
| **Todo** | Approved tasks ready for development |
| **In Progress** | Active development |
| **To Review** | Awaiting code review |
| **To Rework** | Needs fixes, returns to In Progress |
| **Done** | Completed and approved |
**Manual Statuses:** Canceled, Duplicate
---
## Related Documentation
- [tasks/README.md](./README.md) - Task system workflow and rules
---
**Template Version:** 3.0.0 (Epic grouping in ALL Work in Progress sections with examples)
**Last Updated:** 2025-11-15

274
skills/ln-113-tasks-docs-creator/references/questions.md Normal file
View File

@@ -0,0 +1,274 @@
# Task Management Documentation Questions
**Purpose:** Define validation questions for task management system (tasks/README.md, kanban_board.md). Used in CREATE mode (user answers questions) and VALIDATE mode (check document compliance).
**Format:** Document → Questions (with target sections) → Validation Heuristics → Auto-Discovery → Special Handling
---
## Table of Contents
| Document | Questions | Auto-Discovery | Priority | Line |
|----------|-----------|----------------|----------|------|
| [tasks/README.md](#tasksreadmemd) | 3 | None | High | L35 |
| [kanban_board.md](#kanban_boardmd) | 2 | Placeholder Detection | Critical | L110 |
**Priority Legend:**
- **Critical:** Must answer all questions (Linear Configuration required for workflow)
- **High:** Strongly recommended (standard workflow content)
**Auto-Discovery Legend:**
- **None:** No auto-discovery needed (workflow is standardized)
- **Placeholder Detection:** Detect and replace placeholders with user input
---
<!-- DOCUMENT_START: tasks/README.md -->
## tasks/README.md
**File:** docs/tasks/README.md
**Target Sections:** Linear Integration, Task Workflow, Task Templates
**Rules for this document:**
- Must have SCOPE tag in first 10 lines
- Must explain Linear MCP integration
- Must document state transitions and review criteria
- Must list available task templates
---
<!-- QUESTION_START: 1 -->
### Question 1: How is Linear integrated into the task management system?
**Expected Answer:** Team ID location, issue statuses (Backlog, Todo, In Progress, To Review, Done), label conventions, Linear MCP methods reference, workflow configuration
**Target Section:** ## Core Concepts, ## Critical Rules, ## Linear MCP Methods Reference
**Validation Heuristics:**
- ✅ Contains "Linear" or "MCP" → pass
- ✅ Mentions team ID or team UUID → pass
- ✅ Has workflow states: Backlog, Todo, In Progress, To Review, Done → pass
- ✅ Has "Linear MCP Methods" section with examples → pass
- ✅ Length > 100 words → pass
**Auto-Discovery:**
- None needed (standardized workflow provided by template)
**MCP Ref Hints:**
- Research "Linear API MCP integration"
- Search "Linear issue workflow states"
<!-- QUESTION_END: 1 -->
---
<!-- QUESTION_START: 2 -->
### Question 2: What are the task state transitions and review criteria?
**Expected Answer:** State transition rules (Backlog → Todo → In Progress → To Review → Done), review criteria, rework process, Epic Grouping Pattern
**Target Section:** ## Task Workflow, ## Core Concepts
**Validation Heuristics:**
- ✅ Contains "Backlog" or "Todo" or "In Progress" → pass
- ✅ Mentions "Review" or "To Review" → pass
- ✅ Mentions "Done" or "Completed" → pass
- ✅ Has workflow states diagram or table → pass
- ✅ Mentions "Epic Grouping" → pass
- ✅ Length > 60 words → pass
**Auto-Discovery:**
- None needed (standard workflow states)
**MCP Ref Hints:**
- None needed
<!-- QUESTION_END: 2 -->
---
<!-- QUESTION_START: 3 -->
### Question 3: What task templates are available and how to use them?
**Expected Answer:** List of templates (Epic, Story, Task, Test Task), usage guidelines, required sections, links to template files
**Target Section:** ## Task Workflow, ## Critical Rules
**Validation Heuristics:**
- ✅ Contains "template" (case insensitive) → pass
- ✅ Mentions "Epic" or "Story" or "Task" → pass
- ✅ Has links to template files or references → pass
- ✅ Mentions "Story-Level Test Strategy" or testing → pass
- ✅ Length > 40 words → pass
**Auto-Discovery:**
- None needed (templates provided by other skills)
**MCP Ref Hints:**
- None needed
<!-- QUESTION_END: 3 -->
---
**Overall File Validation:**
- ✅ Has SCOPE tag in first 10 lines: `<!-- SCOPE: Task tracking system workflow and rules ONLY -->`
- ✅ Total length > 200 words (meaningful content)
- ✅ Has Maintenance section at end
<!-- DOCUMENT_END: tasks/README.md -->
---
<!-- DOCUMENT_START: kanban_board.md -->
## kanban_board.md
**File:** docs/tasks/kanban_board.md
**Target Sections:** Linear Configuration, Work in Progress (Epic Tracking)
**Rules for this document:**
- Must have SCOPE tag in first 10 lines
- Must have Linear Configuration section with Team Name, Team UUID, Team Key
- Must have Epic tracking table or placeholder
- Single Source of Truth for Next Epic/Story Numbers
---
<!-- QUESTION_START: 1 -->
### Question 1: What is the Linear team configuration?
**Expected Answer:** Team Name, Team UUID (valid format), Team Key (2-4 uppercase letters), Workspace URL, Next Epic Number (≥1), Next Story Number (≥1)
**Target Section:** ## Linear Configuration, ## Epic Story Counters
**Validation Heuristics:**
- ✅ Has Team Name (not placeholder `[TEAM_NAME]`) → pass
- ✅ Has valid UUID format (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) → pass
- ✅ Has Team Key (2-4 uppercase letters, e.g., PROJ, WEB, API) → pass
- ✅ Has Next Epic Number (integer ≥ 1) → pass
- ✅ Has Next Story Number (integer ≥ 1) → pass
- ✅ Has Workspace URL or Team ID → pass
**Auto-Discovery:**
- **Placeholder Detection Pattern:**
- Check for: `[TEAM_NAME]`, `[TEAM_UUID]`, `[TEAM_KEY]`
- If placeholders found → Trigger interactive user prompt (see Special Handling)
- If real values present → Validate format only
**Special Handling (Phase 3 VALIDATE CONTENT):**
**Placeholder Detection:**
```
Pattern: [TEAM_NAME], [TEAM_UUID], [TEAM_KEY]
If ANY placeholder present → Interactive Setup Mode
If NO placeholders → Validation Mode
```
**Interactive Setup Mode (if placeholders detected):**
1. **Prompt user for Team Name:**
- Question: "What is your Linear Team Name?"
- Validation: Non-empty string
- Example: "My Project Team"
2. **Prompt user for Team UUID:**
- Question: "What is your Linear Team UUID?"
- Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
- Validation Regex: `/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/`
- If invalid → Re-prompt with error: "Invalid UUID format. Expected: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (lowercase hex)"
- Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
3. **Prompt user for Team Key:**
- Question: "What is your Linear Team Key (2-4 uppercase letters)?"
- Format: 2-4 uppercase letters
- Validation Regex: `/^[A-Z]{2,4}$/`
- If invalid → Re-prompt with error: "Invalid Team Key format. Expected: 2-4 uppercase letters (e.g., PROJ, WEB, API)"
- Example: "PROJ"
4. **Replace placeholders:**
- Replace `[TEAM_NAME]` → `{user_team_name}`
- Replace `[TEAM_UUID]` → `{user_team_uuid}`
- Replace `[TEAM_KEY]` → `{user_team_key}`
- Replace `[WORKSPACE_URL]` → `https://linear.app/{workspace_slug}` (if placeholder exists)
5. **Set initial counters:**
- Set "Next Epic Number" → 1
- Set "Next Story Number" → 1
6. **Update Last Updated date:**
- Replace `[YYYY-MM-DD]` → `{current_date}`
7. **Save updated kanban_board.md**
8. **Log success:**
```
✓ Linear configuration updated:
- Team Name: {user_team_name}
- Team UUID: {user_team_uuid}
- Team Key: {user_team_key}
- Next Epic Number: 1
- Next Story Number: 1
```
**Validation Mode (if real values present):**
1. **Extract existing values:**
- Extract Team UUID from line matching: `Team UUID: {value}`
- Extract Team Key from line matching: `Team Key: {value}`
2. **Validate formats:**
- UUID: `/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/`
- Team Key: `/^[A-Z]{2,4}$/`
3. **If validation fails:**
```
⚠ Invalid format detected in Linear Configuration:
- Team UUID: {uuid} (expected: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
- Team Key: {key} (expected: 2-4 uppercase letters)
Fix manually or re-run skill to replace with correct values.
```
4. **If validation passes:**
```
✓ Linear Configuration valid (Team: {name}, UUID: {uuid}, Key: {key})
```
**MCP Ref Hints:**
- Research "Linear team UUID format"
- Search "Linear workspace configuration"
<!-- QUESTION_END: 1 -->
---
<!-- QUESTION_START: 2 -->
### Question 2: Are Epics being tracked in the board?
**Expected Answer:** Table with Epic data (Epic ID, Name, Status, Progress) or placeholder ("No active epics")
**Target Section:** ## Work in Progress (Epics Overview subsection)
**Validation Heuristics:**
- ✅ Has "Epic" or "Epics Overview" section header → pass
- ✅ Has table with columns: Epic, Name, Status, Progress (or similar) → pass
- ✅ OR has placeholder: "No active epics" or "No epics yet" → pass
- ✅ Length > 20 words → pass
**Auto-Discovery:**
- None needed (Epics are populated by workflow skills: ln-210, ln-220, ln-300)
**MCP Ref Hints:**
- None needed
<!-- QUESTION_END: 2 -->
---
**Overall File Validation:**
- ✅ Has SCOPE tag in first 10 lines: `<!-- SCOPE: Quick navigation to active tasks in Linear -->`
- ✅ Has Linear Configuration section with valid Team Name, UUID, Key
- ✅ Has Epic Story Counters table
- ✅ Has Maintenance section at end
<!-- DOCUMENT_END: kanban_board.md -->
---
**Version:** 1.0
**Last Updated:** 2025-11-18

541
skills/ln-113-tasks-docs-creator/references/tasks_readme_template.md Normal file
View File

@@ -0,0 +1,541 @@
# Task Tracking System
> **SCOPE:** Task tracking system workflow and rules ONLY. Contains task lifecycle, naming conventions, and integration rules. DO NOT add: actual task details (→ task files), kanban status (→ kanban_board.md), or implementation guides (→ guides/).
---
## Overview
This folder contains the project's task management system, organizing all development work into trackable units with clear status progression.
### Folder Structure
```
docs/tasks/
├── README.md # This file - Task tracking workflow and rules
└── kanban_board.md # Live navigation to active tasks in Linear
```
> [!NOTE]
> All task tracking (Epics, User Stories, tasks) is handled in Linear. Linear is the single source of truth.
**Live Navigation**: [Kanban Board](kanban_board.md)
---
## Core Concepts
### Task Lifecycle
**Workflow:**
```
Backlog/Postponed → Todo → In Progress → To Review → Done
↓
To Rework → (back to In Progress)
```
**Statuses:**
- **Backlog:** New tasks requiring estimation and approval
- **Postponed:** Deferred tasks for future iterations
- **Todo:** Approved tasks ready for development
- **In Progress:** Currently being developed
- **To Review:** Awaiting code review and validation
- **To Rework:** Needs fixes after review
- **Done:** Completed, reviewed, tested, approved
**Manual Statuses** (not in workflow): Canceled, Duplicate
### Epic Structure
**Organization in Linear:**
- **Epic** = Linear Project (contains all User Stories and tasks for epic)
- **User Story** = Linear Issue with `label: user-story` and `parentId: null`
- **Task** = Linear Issue with `parentId: <UserStoryId>`
**Epic Fields:** Name, description, start date, target date, project lead
**User Story Format:** "As a... I want... So that..." + Given-When-Then acceptance criteria
**Task Format:** Context, requirements, acceptance criteria, implementation notes
### Foundation-First Execution Order
**Critical Rule**: Foundation tasks are executed BEFORE consumer tasks (for testability).
**Definitions**:
- **Foundation** = Database, Repository, core services
- **Consumer** = API endpoints, Frontend components that USE foundation
**Rationale**: Each layer is testable when built (can't test API without working DB).
**Example**:
```
✅ CORRECT EXECUTION ORDER:
Task 1: Database schema + Repository (foundation)
Task 2: Service layer with business logic
Task 3: API endpoint (consumer)
Task 4: Frontend dashboard (consumer)
❌ WRONG (can't test):
Task 1: Frontend dashboard calls /api/users
Task 2: API endpoint (no DB to test against)
```
> **Note:** Consumer-First is for API/interface DESIGN (think from consumer perspective), Foundation-First is for EXECUTION ORDER (build testable foundation first).
---
## Critical Rules
### Rule 1: Linear Integration (MCP Methods ONLY)
**CRITICAL**: Use ONLY `mcp__linear-server__*` methods for all Linear operations.
**PROHIBITED**:
- `gh` command (GitHub CLI)
- GitHub API calls
- Direct Linear API calls
- Manual task creation in Linear UI (for automated workflows)
**Rationale**:
- MCP Linear provides type-safe, validated operations
- Prevents data inconsistencies
- Ensures proper error handling
**See**: [Linear MCP Methods Reference](#linear-mcp-methods-reference) below
---
### Rule 2: Integration Rules
#### Tests
**Rule**: Tests are created ONLY in the final Story task (Story Finalizer test task).
**NEVER** create:
- Separate test tasks during implementation
- Tests in implementation tasks (implementation tasks focus on feature code only)
**Process**:
1. Implementation tasks (1-6 tasks) → To Review → Done
2. ln-340-story-quality-gate Pass 1 → Manual testing
3. ln-350-story-test-planner → Creates Story Finalizer test task
4. ln-334-test-executor → Implements all tests (E2E, Integration, Unit)
**Rationale**: Atomic testing strategy, prevents test duplication, ensures comprehensive coverage.
#### Documentation
**Rule**: Documentation is ALWAYS integrated in feature tasks (same task as implementation).
**NEVER** create:
- Separate documentation tasks
- "Update README" tasks
- "Write API docs" tasks
**Process**: Implementation task includes both code AND documentation updates in Definition of Done.
**Rationale**: Ensures documentation stays in sync with code, prevents documentation debt.
---
### Rule 3: Story-Level Test Strategy
**Value-Based Testing**: Test only scenarios with Priority ≥15 (calculated by Impact × Likelihood).
**Test Limits per Story**:
| Test Type | Min | Max | Purpose |
|-----------|-----|-----|---------|
| **E2E Tests** | 2 | 5 | End-to-end user workflows (Priority ≥15) |
| **Integration Tests** | 3 | 8 | Component interactions, external APIs |
| **Unit Tests** | 5 | 15 | Business logic, edge cases |
| **Total** | 10 | 28 | Complete Story coverage |
**Example**:
```
Story: User Authentication
- E2E: 3 tests (login success, login failure, session expiry)
- Integration: 5 tests (OAuth flow, token refresh, database session storage, Redis cache, logout)
- Unit: 8 tests (password validation, email validation, token generation, permission checks, etc.)
Total: 16 tests (within 10-28 range)
```
**Reference**: [Risk-Based Testing Guide](../reference/guides/risk-based-testing-guide.md) for Priority calculation.
---
### Rule 4: Context Budget Rule
- [ ] **CRITICAL: Minimize context pollution in kanban_board.md**
**Rule:** [kanban_board.md](./kanban_board.md) contains ONLY links and titles - no descriptions, no implementation notes.
**Board Structure:**
Single hierarchical view: **Status → Epic → User Story → Tasks**
**Sections:**
1. **Work in Progress** - Hierarchical task tracking (Backlog → Todo → In Progress → To Review → To Rework → Done → Postponed)
2. **Epics Overview** - Portfolio-level status (Active + Completed epics)
**Format Rules:**
**User Story:**
- Format: `📖 [{{TEAM_KEY}}-XX: USYYY Title](link)` + optional `✅ APPROVED`
- 2-space indent from Epic
- Always shows parent epic context
- Can exist without tasks ONLY in Backlog status (with note: `_(tasks not created yet)_`)
**Task:**
- Format: ` - [{{TEAM_KEY}}-XX: EPYY_ZZ Title](link)` (2-space indent + dash)
- 4-space total indent (2-space base from Story + 2-space for dash)
- Always nested under parent User Story
- Cannot exist without parent story
**Epic Grouping:**
- Each status section grouped by: `**Epic N: Epic Name**` (bold header)
- Stories listed under epic with 2-space indent
- Tasks listed under stories with 4-space indent (2-space base + 2-space for dash)
**Status-Specific Limits:**
- **Backlog:** All stories (tasks optional, use `_(tasks not created yet)_` if none)
- **Todo/In Progress/To Review/To Rework:** All stories with all tasks
- **Done:** Maximum 5 tasks total across all stories (show most recent)
- **Postponed:** All stories with all tasks
**Rationale:**
- Single view eliminates need to "jump" between sections
- Natural hierarchy matches mental model: Status → Epic → Story → Task
- Story context always visible with its tasks
- Reduced cognitive load: one structure, not three
- Minimize context size for AI agents
- Fast navigation at all levels (status/epic/story/task)
---
## Task Workflow
### Planning Guidelines
**Optimal Task Size**: 3-5 hours per task
**Task Granularity**:
- Too small (< 2 hours): Merge with related tasks
- Too large (> 8 hours): Split into subtasks
- Sweet spot (3-5 hours): Maximum productivity, clear acceptance criteria
**Story Limits**:
- Implementation tasks: 1-6 tasks per Story
- Test task: 1 Story Finalizer test task (created after implementation)
- Total: Max 7 tasks per Story
### Workflow Skills
| Category | Skill | Purpose |
|----------|-------|---------|
| **Planning** | ln-210-epic-coordinator | Decompose scope → 3-7 Epics |
| | ln-220-story-coordinator | Decompose Epic → 5-10 Stories (with Phase 3 Library Research) |
| | ln-310-story-decomposer | Decompose Story → 1-6 Implementation Tasks |
| | ln-350-story-test-planner | Plan Story Finalizer test task (after manual testing) |
| **Validation** | ln-320-story-validator | Auto-fix Stories/Tasks → Approve (Backlog → Todo) |
| **Execution** | ln-330-story-executor | Orchestrate Story execution (delegates to ln-31/ln-34/ln-32) |
| | ln-331-task-executor | Execute implementation tasks (Todo → In Progress → To Review) |
| | ln-334-test-executor | Execute Story Finalizer test tasks (11 sections) |
| | ln-332-task-reviewer | Review tasks (To Review → Done/Rework) |
| | ln-333-task-rework | Fix tasks after review (To Rework → To Review) |
| **Quality** | ln-340-story-quality-gate | Two-pass review (Code Quality → Regression → Manual Testing) |
| | ln-341-code-quality-checker | Analyze code for DRY/KISS/YAGNI violations |
| | ln-342-regression-checker | Run existing test suite |
| | ln-343-manual-tester | Perform manual testing via curl/puppeteer |
| **Documentation** | ln-114-project-docs-creator | Create project docs (requirements, architecture, specs) |
| | ln-322-adr-creator | Create ADRs (architecture decisions) |
| | ln-321-guide-creator | Create guides (reusable patterns) |
| | ln-323-manual-creator | Create manuals (API references) |
---
## Project Configuration
### Quality Commands
```bash
# Docker development environment
{{DOCKER_COMMAND}}
# Run tests
{{TEST_COMMAND}}
# Run tests with coverage
{{COVERAGE_COMMAND}}
# Type checking
{{TYPE_CHECK_COMMAND}}
# Linting
{{LINT_COMMAND}}
```
### Documentation Structure
Core documentation:
- [Requirements](../project/requirements.md) - Functional requirements (FR-XXX-NNN) with MoSCoW prioritization
- [Architecture](../project/architecture.md) - System architecture (C4 Model, arc42)
- [Technical Specification](../project/technical_specification.md) - Implementation details
- [ADRs](../reference/adrs/) - Architecture Decision Records
- [Guides](../reference/guides/) - Project patterns and best practices
- [Manuals](../reference/manuals/) - Package API references
### Label Taxonomy
**Functional Labels**: `feature`, `bug`, `refactoring`, `documentation`, `testing`, `infrastructure`
**Type Labels**: `user-story`, `implementation-task`, `test-task`
**Status Labels** (auto-managed by Linear): `backlog`, `todo`, `in-progress`, `to-review`, `to-rework`, `done`, `canceled`
### Test Audit History (Optional)
**Test Audit:** Every +50 tests → review new files, delete framework tests. Last: {{AUDIT_DATE}} ({{OLD_COUNT}} → {{NEW_COUNT}})
---
## Linear MCP Methods Reference
### Core Operations
**Issues**:
```python
# List issues
mcp__linear-server__list_issues(
team="TeamName", # Team name or ID
state="In Progress", # State name or ID
assignee="me", # User ID, name, email, or "me"
limit=50 # Max 250
)
# Get issue details
mcp__linear-server__get_issue(
id="PROJ-123" # Issue ID
)
# Create issue
mcp__linear-server__create_issue(
team="TeamName", # Required: Team name or ID
title="Task title", # Required: Issue title
description="...", # Markdown description
state="Todo", # State name or ID
assignee="me", # User ID, name, email, or "me"
parentId="parent-uuid", # For tasks (parent Story UUID)
labels=["feature", "backend"] # Label names or IDs
)
# Update issue
mcp__linear-server__update_issue(
id="PROJ-123", # Required: Issue ID
state="Done", # State name or ID
description="...", # Updated description
assignee="me" # Reassign
)
```
**Projects** (Epics):
```python
# List projects
mcp__linear-server__list_projects(
team="TeamName", # Filter by team
state="started", # Filter by state
limit=50
)
# Get project
mcp__linear-server__get_project(
query="Epic 1" # ID or name
)
# Create project (Epic)
mcp__linear-server__create_project(
team="TeamName", # Required
name="Epic 1: Auth", # Required
description="...", # Epic description
state="planned" # Epic state
)
# Update project
mcp__linear-server__update_project(
id="project-uuid", # Required
state="started", # Update state
description="..." # Update description
)
```
**Teams**:
```python
# List teams
mcp__linear-server__list_teams()
# Get team
mcp__linear-server__get_team(
query="TeamName" # UUID, key, or name
)
```
**Labels**:
```python
# List labels
mcp__linear-server__list_issue_labels(
team="TeamName" # Optional: filter by team
)
# Create label
mcp__linear-server__create_issue_label(
name="backend", # Required
color="#FF5733", # Hex color
teamId="team-uuid" # Optional: team-specific label
)
```
**Comments**:
```python
# List comments
mcp__linear-server__list_comments(
issueId="issue-uuid" # Required
)
# Create comment
mcp__linear-server__create_comment(
issueId="issue-uuid", # Required
body="Comment text" # Required: Markdown
)
```
### Parameter Patterns
**Common Filters**:
```python
# By assignee
assignee="me" # Current user
assignee="user@example.com" # By email
assignee="user-uuid" # By UUID
# By state
state="Todo" # By name
state="state-uuid" # By UUID
# By team
team="TeamName" # By name
team="team-uuid" # By UUID
# By label
label="feature" # By name
label="label-uuid" # By UUID
```
**Pagination**:
```python
# Limit results
limit=50 # Default: 50, Max: 250
# Pagination
after="cursor-id" # Start from cursor
before="cursor-id" # End at cursor
```
**Date Filters**:
```python
# ISO-8601 date-time
createdAt="2025-01-01T00:00:00Z"
# Duration (relative)
createdAt="-P1D" # Created in last 1 day
updatedAt="-P7D" # Updated in last 7 days
```
### Examples
**Example 1: Get all In Progress tasks for current user**
```python
issues = mcp__linear-server__list_issues(
team="ProjectTeam",
state="In Progress",
assignee="me",
limit=100
)
```
**Example 2: Create Story (User Story)**
```python
story = mcp__linear-server__create_issue(
team="ProjectTeam",
title="US001 User Login",
description="User story description...",
state="Backlog",
labels=["user-story", "feature"]
)
```
**Example 3: Create Task (child of Story)**
```python
task = mcp__linear-server__create_issue(
team="ProjectTeam",
title="EP1_01 Implement JWT tokens",
description="Task description...",
state="Todo",
parentId="story-uuid", # Link to parent Story
labels=["implementation-task", "backend"]
)
```
**Example 4: Move task to Done**
```python
mcp__linear-server__update_issue(
id="PROJ-123",
state="Done"
)
```
**Example 5: Create Epic (Project)**
```python
epic = mcp__linear-server__create_project(
team="ProjectTeam",
name="Epic 1: Authentication System",
description="Epic description...",
state="planned"
)
```
---
## Maintenance
**Update Triggers**:
- When adding new workflow skills
- When changing task lifecycle statuses
- When updating Critical Rules
- When modifying Linear integration patterns
- When changing test strategy limits
**Verification**:
- All Linear MCP method examples are valid
- Workflow skills table matches available skills
- Critical Rules align with current development principles
- Test limits match risk-based testing guide
**Last Updated**: {{DATE}}
---
**Template Version:** 1.0.0
**Template Last Updated:** 2025-11-15

457
skills/ln-114-project-docs-creator/SKILL.md Normal file
View File

@@ -0,0 +1,457 @@
---
name: ln-114-project-docs-creator
description: Creates and validates 7 project docs (requirements, architecture, tech_stack, api_spec, database_schema, design_guidelines, runbook). Fourth worker in ln-110-documents-pipeline.
---
# Project Documentation Creator
This skill creates and validates technical project documentation following industry best practices (ISO/IEC/IEEE standards, arc42, C4 Model, ADR format).
## When to Use This Skill
**This skill is a WORKER** invoked by **ln-110-documents-pipeline** orchestrator.
This skill should be used directly when:
- Creating only project documentation (7 docs: requirements, architecture, tech_stack, api_spec, database_schema, design_guidelines, runbook)
- Validating existing project documentation
- NOT creating full documentation structure (use ln-110-documents-pipeline for complete setup)
**Part of workflow**: ln-110-documents-pipeline (orchestrator) → ln-111-root-docs-creator → ln-112-reference-docs-creator → ln-113-tasks-docs-creator → **ln-114-project-docs-creator** → ln-115-presentation-creator → ln-116-test-docs-creator
## How It Works
The skill follows a 4-phase workflow: **CREATE** → **VALIDATE STRUCTURE** → **VALIDATE CONTENT** → **FINALIZE**. Each phase builds on the previous, ensuring complete structure and semantic validation.
---
### Phase 1: Create Structure
**Objective**: Establish project documentation files (3-7 files based on project type).
**Process**:
**1.1 Check existing files**:
- Use Glob to scan `docs/project/*.md`
- Check which of 7 project docs already exist:
- requirements.md (ALWAYS needed)
- architecture.md (ALWAYS needed)
- tech_stack.md (ALWAYS needed)
- api_spec.md (Backend/Full-stack only)
- database_schema.md (if database detected)
- design_guidelines.md (Frontend/Full-stack only)
- runbook.md (Docker-based projects)
- Build list of MISSING files
**1.2 Determine conditional templates**:
- **api_spec.md**: Create if Backend/Full-stack project
- Detect: Check package.json for backend frameworks (express, fastify, nestjs) OR python/go/java runtime
- Skip for Frontend-only projects
- **database_schema.md**: Create if database detected
- Detect: Check package.json for database libraries (pg, mongoose, mysql2, sqlite3, prisma)
- Skip if no database found
- **design_guidelines.md**: Create if Frontend framework detected
- Detect: Check package.json for frontend frameworks (react, vue, angular, svelte, next)
- Skip for Backend-only projects
**1.3 Create missing templates**:
- For each missing file, use Write tool to create from `references/templates/`:
- `requirements_template.md` → `docs/project/requirements.md` (if missing)
- `architecture_template.md` → `docs/project/architecture.md` (if missing)
- `tech_stack_template.md` → `docs/project/tech_stack.md` (if missing)
- `api_spec_template.md` → `docs/project/api_spec.md` (if missing and needed)
- `database_schema_template.md` → `docs/project/database_schema.md` (if missing and needed)
- `design_guidelines_template.md` → `docs/project/design_guidelines.md` (if missing and needed)
- `runbook_template.md` → `docs/project/runbook.md` (if missing)
- Track created file list (for Phase 2-3 validation)
**1.4 Log summary**:
```
✓ Project documentation structure:
- Created: X new files
- Preserved: Y existing files
- Skipped: Z conditional files (not needed for this project type)
```
**Output**:
```
docs/project/
├── requirements.md (created or existing)
├── architecture.md (created or existing)
├── tech_stack.md (created or existing)
├── api_spec.md (created or existing, conditional)
├── database_schema.md (created or existing, conditional)
├── design_guidelines.md (created or existing, conditional)
└── runbook.md (created or existing, conditional)
```
---
### Phase 2: Validate Structure
**Objective**: Ensure project documentation complies with structural requirements and auto-fix violations.
**Process**:
**2.1 Check SCOPE tags** (all created files):
- Read first 5 lines of each file created in Phase 1
- Check for `<!-- SCOPE: ... -->` tag
- Expected patterns:
- requirements.md: `<!-- SCOPE: Functional requirements ONLY (FR-XXX-NNN) -->`
- architecture.md: `<!-- SCOPE: arc42 architecture documentation with C4 Model -->`
- tech_stack.md: `<!-- SCOPE: Technology stack with versions and Docker configuration -->`
- api_spec.md: `<!-- SCOPE: API specification (OpenAPI 3.0 compatible) -->`
- database_schema.md: `<!-- SCOPE: Database schema with ER diagrams -->`
- design_guidelines.md: `<!-- SCOPE: UI/UX design system and guidelines -->`
- runbook.md: `<!-- SCOPE: Operations guide (local/testing/production) -->`
- If missing:
- Use Edit tool to add SCOPE tag at line 1 (after first heading)
- Track violation count
- Log: "✓ SCOPE tags: [added N/all present]"
**2.2 Check required sections** (from questions.md):
- Load `references/questions.md` using Read tool
- For each document created in Phase 1:
- Extract expected sections from questions.md
- Check if section headers exist in document
- If missing:
- Use Edit tool to add section with placeholder
- Track violation count
- Examples:
- requirements.md: ## Functional Requirements
- architecture.md: ## 1. Introduction and Goals, ## 2. Constraints, ..., ## 11. Glossary
- tech_stack.md: ## Frontend Technologies, ## Backend Technologies, ## Database, ## Additional Technologies
- Log: "✓ Required sections: [added N sections across M files/all present]"
**2.3 Check Maintenance section** (all created files):
- Search for `## Maintenance` header in each file
- If missing:
- Use Edit tool to add at end of file:
```markdown
## Maintenance
**Last Updated:** [current date]
**Update Triggers:**
- [Document-specific triggers]
**Verification:**
- [ ] All sections have content (no placeholders)
- [ ] Diagrams render correctly
- [ ] Links to other docs are valid
```
- Track violation count
- Log: "✓ Maintenance sections: [added N/all present]"
**2.4 Check POSIX file endings** (all created files):
- Check if each file ends with single blank line
- If missing:
- Use Edit tool to add final newline
- Track fix count
- Log: "✓ POSIX compliance: [fixed N files/all compliant]"
**2.5 Conditional checks**:
- **api_spec.md**: Only validate if Backend/Full-stack project detected
- Skip validation if Frontend-only project
- Log: "ℹ api_spec.md skipped (Frontend-only project)"
- **database_schema.md**: Only validate if database detected in dependencies
- Check package.json for database libraries (pg, mongoose, mysql2, sqlite3)
- Skip if no database found
- Log: "ℹ database_schema.md skipped (no database detected)"
- **design_guidelines.md**: Only validate if Frontend framework detected
- Check package.json for frontend frameworks (react, vue, angular, svelte)
- Skip if Backend-only project
- Log: "ℹ design_guidelines.md skipped (Backend-only project)"
**2.6 Report validation**:
- Log summary:
```
✅ Structure validation complete:
- SCOPE tags: [added N/all present]
- Missing sections: [added N sections across M files/all present]
- Maintenance sections: [added N/all present]
- POSIX endings: [fixed N files/all compliant]
- Conditional checks: [skipped K files based on project type]
```
- If violations found: "⚠️ Auto-fixed [total] structural violations"
---
### Phase 3: Validate Content
**Objective**: Ensure each section answers its questions with meaningful content using semantic validation.
**Process**:
**3.1 Load validation spec**:
- Read `references/questions.md` using Read tool
- Parse all 27 questions with validation heuristics, auto-discovery hints, and MCP Ref hints
- Build validation map: {document → [{question, section, heuristics, auto_discovery, mcp_ref}]}
**3.2 Validate sections** (parametric loop for ~27 questions):
For each question in questions.md:
1. **Extract section content**:
- Read target document (requirements.md, architecture.md, etc.)
- Extract section content between headers
- If section missing → error (should have been added in Phase 2.2)
2. **Check if content answers question**:
- Apply validation heuristics from questions.md
- Examples:
- "Has FR-XXX identifiers" → scan for pattern `FR-\w+-\d+`
- "Length > 100 words" → count words in section
- "Has Mermaid diagram" → check for ```mermaid code blocks
- If ANY heuristic passes → content valid, skip to next question
- If ALL fail → content invalid, continue
3. **Auto-discovery** (if content invalid or has placeholders):
- Execute auto-discovery hints from questions.md
- Examples:
- **package.json scanning**:
- Read package.json
- Extract dependencies, devDependencies, scripts, engines, version
- Identify frameworks (react → Frontend, express → Backend)
- **src/ directory structure**:
- Scan src/ using Glob tool
- Detect architecture patterns:
- `src/controllers/`, `src/services/`, `src/repositories/` → Layered architecture
- `src/modules/`, `src/features/` → Modular architecture
- `src/pages/`, `src/components/` → Frontend component structure
- **docker-compose.yml**:
- Read docker-compose.yml if exists
- Extract services (postgres, mongo, redis, rabbitmq)
- Populate tech_stack.md and database_schema.md sections
- **.env.example**:
- Read .env.example if exists
- Extract configuration variables
- Populate runbook.md environment variables section
- **migrations/ directory**:
- Scan migrations/ or db/migrations/
- Extract table names from CREATE TABLE statements
- Populate database_schema.md tables section
- If auto-discovery successful:
- Use Edit tool to populate section with discovered data
- Track change: `sections_populated += 1`
- Skip MCP Ref and user questions
- If auto-discovery fails → continue to MCP Ref
4. **MCP Ref research** (if auto-discovery fails):
- Execute MCP Ref hints from questions.md
- Examples:
- Framework features: `mcp__context7__resolve-library-id("React")` → `mcp__context7__get-library-docs("/facebook/react", topic="React 18 features")`
- Architecture patterns: `mcp__Ref__ref_search_documentation("Layered architecture vs microservices")`
- Library standards: `mcp__Ref__ref_search_documentation("Repository pattern best practices")`
- Technology comparison: `mcp__Ref__ref_search_documentation("PostgreSQL vs MongoDB comparison")`
- If research yields useful information:
- Use Edit tool to populate section with research summary
- Track change: `sections_researched += 1`
- Skip user questions
- If research fails → continue to user fallback
5. **User question fallback** (if auto-discovery AND MCP Ref fail):
- Ask user the question from questions.md
- Examples:
- "What are the main functional requirements?" (if no hints found)
- "What are the system quality goals?" (if no constraints discovered)
- "What is the primary architecture pattern?" (if src/ structure ambiguous)
- Wait for user response
- Use Edit tool to populate section with user's answer
- Track change: `sections_user_input += 1`
6. **Track validation result**:
- Log per question: "[Document] Section X: [valid/populated via auto-discovery/populated via MCP Ref/populated via user input]"
**3.3 Priority-based validation** (optimize token usage):
- **Critical priority** (requirements.md, architecture.md, runbook.md):
- Validate all sections
- Ask user questions if auto-discovery/MCP Ref fail
- **High priority** (tech_stack.md, api_spec.md, database_schema.md):
- Validate all sections
- Prefer auto-discovery and MCP Ref
- Only ask critical user questions
- **Medium priority** (design_guidelines.md):
- Validate required sections only
- Skip if Frontend-only and user confirms can use template defaults
**3.4 Report content validation**:
- Log summary:
```
✅ Content validation complete:
- Questions checked: 27 (or 22 for backend-only, 24 for frontend-only)
- Already valid: [count] sections
- Populated via auto-discovery: [count] sections
- Populated via MCP Ref: [count] sections
- Populated via user input: [count] sections
- Placeholders kept: [count] sections (optional content)
```
**Auto-discovery success rate example**:
```
Full-stack Node.js project with package.json + docker-compose.yml:
- Auto-discovery: ~18/27 questions (67%)
- MCP Ref: ~5/27 questions (18%)
- User input: ~4/27 questions (15%)
```
---
### Phase 4: Finalization
**Objective**: Provide complete overview and next steps.
**Process**:
1. List all project files with status (3-7 files depending on project type):
- `docs/project/requirements.md` (ALWAYS) - created or preserved
- `docs/project/architecture.md` (ALWAYS) - created or preserved
- `docs/project/tech_stack.md` (ALWAYS) - created or preserved
- `docs/project/api_spec.md` (if API/Backend/Full-stack) - created or preserved
- `docs/project/database_schema.md` (if uses database) - created or preserved
- `docs/project/design_guidelines.md` (if Frontend/Full-stack) - created or preserved
- `docs/project/runbook.md` (if Docker-based) - created or preserved
2. Report summary:
- "✓ Project documentation complete: Created X new files, preserved Y existing"
- "Validation: Structure [N fixes], Content [M updates]"
**Output**: Summary message with project files status (created vs preserved)
---
## Complete Output Structure
```
docs/
└── project/
├── requirements.md # Functional Requirements (FR-XXX-NNN) ONLY
├── architecture.md # arc42-based architecture with C4 Model
├── tech_stack.md # Technology stack, versions, Docker setup
├── api_spec.md # API endpoints, auth, error codes (conditional)
├── database_schema.md # ER diagrams, tables, migrations (conditional)
├── design_guidelines.md # UI/UX design system (conditional - frontend only)
└── runbook.md # Operations: local/testing/production (conditional)
```
**Conditional files:**
- `api_spec.md` - Created for API/Backend/Full-stack projects
- `database_schema.md` - Created if project uses database (PostgreSQL, MySQL, MongoDB, etc.)
- `design_guidelines.md` - Created for Frontend/Full-stack projects (skipped for backend-only)
- `runbook.md` - Created for Docker-based projects
---
## Reference Files Used
### Document Templates
**Project Document Templates** (used in Phase 1 from `references/templates/`):
- `requirements_template.md` - Functional Requirements ONLY (ISO/IEC/IEEE 29148:2018)
- `architecture_template.md` - arc42-based architecture with C4 Model (ISO/IEC/IEEE 42010:2022)
- `tech_stack_template.md` - Technology stack, versions, Docker configuration
- `api_spec_template.md` - API specification (OpenAPI 3.0 compatible)
- `database_schema_template.md` - ER diagrams, data dictionary, migrations
- `design_guidelines_template.md` - UI/UX design system (WCAG 2.1 Level AA)
- `runbook_template.md` - Operations guide (local/testing/production)
**Validation Specification**:
- `references/questions.md` (v1.0) - 27 questions with validation heuristics:
- Questions each section must answer
- Validation heuristics (checkable criteria)
- Auto-discovery hints (package.json, src/, docker-compose.yml, migrations/)
- MCP Ref hints (external research topics)
---
## Best Practices
- **Idempotent Operations**: ✅ Checks file existence before creation (Phase 1), creates only missing files, preserves existing project docs
- **Conditional Templates**: Only create templates relevant to project type (skip design_guidelines.md for backend-only, skip api_spec.md for frontend-only)
- **Parametric Validation**: Phase 3 uses loop for 27 questions (no code duplication)
- **Auto-discovery First**: Scan actual files before external API calls or user questions
- **Separation of Concerns**: CREATE → VALIDATE STRUCTURE → VALIDATE CONTENT → FINALIZE
- **Document Generation**: English only, explicit IDs (FR-XXX-001), MoSCoW prioritization, meaningful Mermaid diagrams with actual data
- **Token Efficiency**: Reuse discovered data across multiple documents, avoid asking same questions twice
---
## Prerequisites
**Invoked by**: ln-110-documents-pipeline orchestrator
**Requires**:
- `docs/` directory (created by ln-111-root-docs-creator)
**Creates**:
- `docs/project/` directory structure (3-7 files)
- Validated project documentation with structure and content checks
**Idempotent**: ✅ Can be invoked multiple times safely
- Checks file existence before creation
- Skips existing files
- Re-validates on subsequent runs
---
## Definition of Done
Before completing work, verify ALL checkpoints:
**✅ Documents Generated:**
- [ ] All required project documents created successfully (3-7 files depending on project type):
- `docs/project/requirements.md` (ALWAYS)
- `docs/project/architecture.md` (ALWAYS)
- `docs/project/tech_stack.md` (ALWAYS)
- `docs/project/api_spec.md` (if API/Backend/Full-stack)
- `docs/project/database_schema.md` (if uses database)
- `docs/project/design_guidelines.md` (if Frontend/Full-stack)
- `docs/project/runbook.md` (if Docker-based)
- [ ] SCOPE tags included in first 3-5 lines of each document
- [ ] Maintenance sections present in all docs
- [ ] All placeholders replaced with actual content (no `{{PLACEHOLDER}}` remaining)
**✅ Content Quality:**
- [ ] Mermaid diagrams valid syntax (Business Context, Technical Context, C4 diagrams, ER diagrams)
- [ ] Requirement IDs sequential and unique (FR-XXX-001 only)
- [ ] MoSCoW prioritization applied correctly (MUST/SHOULD/COULD/WON'T)
- [ ] Language: English only (per project standards)
- [ ] Docker configuration present in tech_stack.md
**✅ Phase Completion:**
- [ ] Phase 1: Create Structure completed
- [ ] Conditional templates determined (api_spec, database_schema, design_guidelines)
- [ ] Missing files created (3-7 based on project type)
- [ ] Created file list tracked
- [ ] Phase 2: Validate Structure completed
- [ ] SCOPE tags verified/added (all created files)
- [ ] Required sections verified/added (from questions.md)
- [ ] Maintenance sections verified/added (all created files)
- [ ] POSIX file endings verified/fixed
- [ ] Conditional checks performed (api_spec, database_schema, design_guidelines)
- [ ] Phase 3: Validate Content completed
- [ ] questions.md loaded for semantic validation
- [ ] All 27 questions validated (or 22/24 for specific project types)
- [ ] Auto-discovery executed where applicable
- [ ] MCP Ref research executed where needed
- [ ] User fallback questions asked for critical content
- [ ] Content validation report generated
- [ ] Phase 4: Finalization completed
- [ ] Summary displayed with file paths and status
**✅ User Guidance:**
- [ ] Summary message displayed with all file paths
- [ ] User informed: "✓ Project documentation complete (X files created)"
**Output:** Complete project documentation set in `docs/project/` (3-7 MD docs depending on project type)
---
## Technical Details
**Standards**: ISO/IEC/IEEE 29148:2018 (Requirements), ISO/IEC/IEEE 42010:2022 (Architecture), arc42, C4 Model, MoSCoW Prioritization, OWASP Security, WCAG 2.1 Level AA
**Language**: English only
---
**Version:** 12.0.0 (MAJOR: Merged validation into worker. Added Phase 2 structure validation + Phase 3 semantic content validation with extensive auto-discovery (package.json, src/, docker-compose.yml, migrations/) and MCP Ref research. Idempotent - can be invoked multiple times.)
**Last Updated:** 2025-11-18

129
skills/ln-114-project-docs-creator/diagram.html Normal file
View File

@@ -0,0 +1,129 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>ln-114-project-docs-creator - State Diagram</title>
<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
<link rel="stylesheet" href="../shared/css/diagram.css">
</head>
<body>
<div class="container">
<header>
<h1>📚 ln-114-project-docs-creator</h1>
<p class="subtitle">Project Documentation Creator - State Diagram</p>
</header>
<div class="info-box">
<h3>📋 Workflow Overview</h3>
<ul>
<li><strong>Purpose:</strong> Create and validate 7 project docs (requirements, architecture, tech_stack, api_spec, database_schema, design_guidelines, runbook)</li>
<li><strong>Worker for:</strong> ln-110-documents-pipeline orchestrator</li>
<li><strong>Phases:</strong> 4 phases (Phase 1 CREATE → Phase 2 Structure Validation → Phase 3 Content Validation → Phase 4 Finalization)</li>
<li><strong>Validation:</strong> 27 questions with auto-discovery → MCP Ref → user fallback hierarchy</li>
<li><strong>Auto-Discovery:</strong> package.json, src/ structure, docker-compose.yml, migrations/, .env.example scanning</li>
</ul>
</div>
<div class="legend">
<div class="legend-item">
<div class="legend-color color-action"></div>
<span>Creation Action</span>
</div>
<div class="legend-item">
<div class="legend-color color-validation"></div>
<span>Validation</span>
</div>
<div class="legend-item">
<div class="legend-color color-decision"></div>
<span>Decision Point</span>
</div>
</div>
<div class="diagram-container">
<div class="mermaid">
graph TD
Start([Start: Create Project Documentation]) --> Phase1[Phase 1: Create Structure<br/>3-7 files based on project type]
Phase1 --> CheckFiles[Check existing files<br/>docs/project/*.md]
CheckFiles --> DetermineTemplates[Determine conditional templates:<br/>api_spec Backend only<br/>database_schema if DB detected<br/>design_guidelines Frontend only]
DetermineTemplates --> CreateMissing[Create missing templates from references/]
CreateMissing --> Phase2[Phase 2: Validate Structure<br/>Auto-fix violations]
Phase2 --> AutoFix[Auto-fix:<br/>SCOPE tags, required sections,<br/>Maintenance sections, POSIX endings]
AutoFix --> Phase3[Phase 3: Validate Content<br/>27 questions parametric loop]
Phase3 --> ParametricLoop[For each question in questions.md:<br/>Extract section content]
ParametricLoop --> CheckHeuristics{Validation<br/>heuristics pass?}
CheckHeuristics -->|Yes| Valid[Section valid, skip to next question]
CheckHeuristics -->|No| AutoDiscovery
AutoDiscovery[Auto-discovery:<br/>package.json, src/, docker-compose,<br/>migrations/, .env.example]
AutoDiscovery --> DiscoverySuccess{Discovery<br/>successful?}
DiscoverySuccess -->|Yes| PopulateDiscovery[Populate section<br/>with discovered data]
DiscoverySuccess -->|No| MCPRef
MCPRef[MCP Ref research:<br/>Framework features, architecture patterns,<br/>library standards, tech comparisons]
MCPRef --> MCPSuccess{Research<br/>successful?}
MCPSuccess -->|Yes| PopulateRef[Populate section<br/>with research summary]
MCPSuccess -->|No| UserFallback[User question fallback:<br/>Ask user to provide content]
PopulateDiscovery --> MoreQuestions
PopulateRef --> MoreQuestions
UserFallback --> MoreQuestions
Valid --> MoreQuestions
MoreQuestions{More questions<br/>to validate?}
MoreQuestions -->|Yes| ParametricLoop
MoreQuestions -->|No| Phase4
Phase4[Phase 4: Finalization<br/>Generate summary report]
Phase4 --> Summary[Display completion summary:<br/>Files created/preserved,<br/>Sections populated auto vs user]
Summary --> End([End: ✓ 7 project docs created + validated])
%% Styling
classDef action fill:#C8E6C9,stroke:#388E3C,stroke-width:2px
classDef validation fill:#FFF9C4,stroke:#F57C00,stroke-width:2px
classDef decision fill:#FFE0B2,stroke:#E64A19,stroke-width:2px
class Phase1,CheckFiles,DetermineTemplates,CreateMissing,AutoFix,PopulateDiscovery,PopulateRef,UserFallback,Summary action
class Phase2,Phase3,ParametricLoop,AutoDiscovery,MCPRef,Phase4 validation
class CheckHeuristics,DiscoverySuccess,MCPSuccess,MoreQuestions decision
</div>
</div>
<div class="info-box">
<h3>🔑 Key Features</h3>
<ul>
<li><strong>Fourth Worker:</strong> Creates project documentation after task management system (ln-110 → ln-111 → ln-112 → ln-113 → ln-114)</li>
<li><strong>Conditional Templates:</strong> api_spec.md (Backend/Full-stack), database_schema.md (if DB detected), design_guidelines.md (Frontend/Full-stack)</li>
<li><strong>3-Level Validation Hierarchy:</strong> Auto-discovery (67%) → MCP Ref (18%) → User input (15%) for optimal token efficiency</li>
<li><strong>Priority-Based Validation:</strong> Critical (requirements, architecture, runbook) → High (tech_stack, api_spec, database_schema) → Medium (design_guidelines)</li>
<li><strong>Smart Auto-Discovery:</strong> Scans package.json, src/ directory structure, docker-compose.yml, migrations/, .env.example</li>
<li><strong>Parametric Loop:</strong> 27 questions with validation heuristics, auto-discovery hints, MCP Ref hints</li>
</ul>
</div>
<footer>
<p>Generated for ln-114-project-docs-creator skill | Version 12.0.0</p>
<p>Diagram format: Mermaid.js | Last updated: 2025-11-18</p>
</footer>
</div>
<script>
mermaid.initialize({
startOnLoad: true,
theme: 'default',
flowchart: {
useMaxWidth: true,
htmlLabels: true,
curve: 'basis'
}
});
</script>
</body>
</html>

206
skills/ln-114-project-docs-creator/references/guides/automatic_analysis_guide.md Normal file
View File

@@ -0,0 +1,206 @@
# Automatic Analysis Guide
Guide for automatic analysis of project materials and researching 2025 best practices.
---
## Section 1: Analyzing Project Materials
### When to Analyze
Ask user: *"Do you have project materials to analyze? (files, diagrams, docs, code)"*
### Files to Search (use Glob + Read)
**Package managers**: `package.json`, `requirements.txt`, `go.mod`, `pom.xml`, `Gemfile`
**Docker**: `Dockerfile`, `docker-compose.yml`, `docker-compose.test.yml`
**Config**: `tsconfig.json`, `*.env.example`, `.nvmrc`
**Docs**: `README.md`, architecture diagrams
**Code structure**: `src/`, `api/`, `services/`, `tests/`
### Information to Extract
From **package.json / requirements.txt / go.mod**:
- Runtime version (Node 18, Python 3.11, Go 1.21)
- Dependencies → frameworks, databases, auth, cache
- Pre-populate: Q9, Q12
From **Dockerfile**:
- Base image → runtime version
- Multi-stage structure → build optimization
- Pre-populate: Q9, Q12
From **docker-compose.yml**:
- Services → app + db + cache + queue
- Images → database/cache versions
- Volumes → hot-reload setup
- Pre-populate: Q9, Q11
From **docker-compose.test.yml**:
- Test services → db-test, cache-test (isolated)
- Volumes → ./src, ./tests (hot-reload)
- Tmpfs → in-memory test databases
- Command → test framework
- Pre-populate: Q12 (test setup)
### Output Format
```
✓ Analyzed project materials
**Detected**:
- Runtime: [runtime + version]
- Framework: [framework + version]
- Database: [database]
- Architecture: [hints from docker-compose]
**Pre-populated**: Q9, Q12 (partial)
```
---
## Section 2: Researching Best Practices 2025
### When to Research
During **Phase 2, Stage 2** for questions Q9, Q11-Q13.
Ask user first: *"Research best practices automatically? (Y/N)"*
### Research Tools
**MCP Ref** (`mcp__Ref__ref_search_documentation`):
- Query: `"[framework] latest version 2025"`
- Use for: Official docs, version numbers, features
- Then Read: `mcp__Ref__ref_read_url` for details
**WebSearch**:
- Query patterns:
- `"[Tech A] vs [Tech B] 2025 comparison"`
- `"best practices [technology] 2025"`
- `"[pattern] architecture pros cons 2025"`
- Use for: Comparisons, best practices, trends
### Research Strategy by Question
**Q9: Technology Decisions**
1. Check analyzed versions vs 2025 latest
2. MCP Ref: latest stable versions
3. WebSearch: security vulnerabilities, release notes
4. Recommend upgrades if: EOL, security issues, LTS available
**Q11: Architectural Patterns**
1. Identify project type + scale from Stage 1
2. WebSearch: `"[project type] architecture patterns 2025"`
3. Consider scale:
- Small (< 10K users) → Monolith
- Medium (10K-100K) → Microservices
- Large (100K+) → Microservices + Event-Driven
**Q12: Libraries and Frameworks**
1. Based on Q9 + Q11
2. MCP Ref: latest versions for each component
3. WebSearch: compatibility, comparisons
4. Check: ORM, testing framework, validation library
5. Verify compatibility matrix
**Q13: Integrations**
1. Identify needs from Q5 (IN SCOPE)
2. WebSearch comparisons:
- Payments: `"Stripe vs PayPal 2025"`
- Email: `"SendGrid vs AWS SES 2025"`
- Auth: `"Auth0 vs Clerk 2025"`
- Storage: `"AWS S3 vs Cloudinary 2025"`
3. Consider: pricing, DX, compliance, popularity
### Dockerfile Generation
Based on Q12 runtime + framework:
- Latest stable base image
- Multi-stage build (dev + prod)
- Security: non-root user, minimal image
- Generate docker-compose.yml with services from Q11
---
## Section 3: Transition to Interactive Mode
### When to Ask User
**Pause research when**:
1. **Multiple alternatives** (React vs Vue) → present both, ask preference
2. **Insufficient info** (no files found) → ask directly
3. **Unclear goals** (vague Q5) → ask clarifying questions
4. **Always interactive**: Q10, Q14-Q19 (org-specific)
### Alternative Presentation Template
```
"Researched [Category]:
**Option A**: [Tech A]
Pros: [key benefits]
Cons: [key drawbacks]
**Option B**: [Tech B]
Pros: [key benefits]
Cons: [key drawbacks]
Recommendation: [A/B] because [reason]
Which do you prefer? (A/B/Other)"
```
### Fallback to Full Interactive
If no materials OR user declines research → ask all Q9-Q19 interactively
---
## Section 4: Quality Guidelines
### Verification Checklist
- [ ] Version is 2025-current (< 1 year old)
- [ ] Stable release (not beta)
- [ ] No critical security vulnerabilities
- [ ] Compatible with other tech
- [ ] Active community (GitHub stars, updates)
- [ ] Official docs available
### Red Flags (Don't Recommend)
- Last updated > 2 years ago
- Unpatched security vulnerabilities
- Incompatible with stack
- Beta/experimental (unless requested)
- Obscure (<1000 GitHub stars)
### Rationale Format
```
Recommendation: [Technology]
Rationale:
1. [Technical reason]
2. [Ecosystem reason]
3. [Project fit reason]
4. [Industry adoption]
```
---
## Section 5: Execution Flow
### Phase 1.5: Material Analysis
```
User provides materials? (Y/N)
├─ Y: Glob + Read files → Extract info → Report findings
└─ N: Skip to Phase 2
```
### Phase 2, Stage 2: Research & Design
```
Stage 1 complete (Q1-Q8 answered)
↓
Research automatically? (Y/N)
├─ Y: Research Q9, Q11-Q13 → Present recommendations → User accepts/modifies
└─ N: Ask Q9-Q13 interactively
↓
Always ask Q10, Q14-Q19 interactively
```
---
**Version:** 1.0.0
**Last Updated:** 2025-10-29

307
skills/ln-114-project-docs-creator/references/guides/critical_questions.md Normal file
View File

@@ -0,0 +1,307 @@
# Technical Questions for Project Documentation
These 23 technical questions MUST be answered before creating project documentation. They are grouped into 6 categories for structured technical discovery.
**Focus**: This document is **purely technical** - no business metrics, stakeholder management, or budget planning. For technical teams documenting architecture, requirements, and implementation details.
## Priority Order: Context First, Questions Last
**CRITICAL**: Interactive questions are the LAST RESORT. Follow this priority order:
1. **Auto-Discovery (Phase 1.2)** - ALWAYS attempt first
- Search for: package.json, Dockerfile, docker-compose.yml, requirements.txt, pyproject.toml, pom.xml, build.gradle, go.mod, README.md
- Extract: Q9 (runtime versions), Q12 (frameworks, databases, dependencies)
- Benefits: Zero user effort, reduces questions by 2-4
2. **User Materials (Phase 1.3)** - MANDATORY question
- ALWAYS ask: "Do you have existing materials I should review? (design docs, specs, requirements, legacy docs, diagrams, API contracts)"
- If YES: Read and extract answers for Q1-Q23 from materials
- Benefits: Can reduce questions by 10-18 depending on material completeness
3. **Best Practices Research (Phase 1.4)** - AUTO research
- Use MCP Ref to verify 2025 library versions (supplements Q12)
- Use WebSearch for architectural patterns (supplements Q11)
- Use WebSearch for integration best practices (supplements Q13)
- Benefits: Provides current best practices, reduces technical decision questions
4. **Interactive Questions (Phase 2)** - ONLY for remaining questions
- Ask ONLY questions that could NOT be auto-discovered, extracted from materials, or researched
- Show progress: "Already gathered X/23 questions, asking Y remaining questions"
- Benefits: Minimizes user effort, maximizes efficiency
**Example Impact**:
- Optimal scenario (with materials): 18/23 answered automatically → ask only 5 questions
- Typical scenario (no materials): 4/23 answered automatically → ask 19 questions
- Greenfield project: 6/23 answered from materials + research → ask 17 questions
## Question Metadata (3-Stage Discovery)
| Question | Category | Stage | Mode | Research Tools |
|----------|----------|-------|------|----------------|
| Q1-Q3 | Requirements | 1 | interactive | - |
| Q5-Q8 | Scope | 1 | interactive | - |
| Q9 | Tech Stack | 2 | auto-discoverable | package.json, Dockerfile, docker-compose.yml |
| Q10 | Tech Stack | 2 | interactive | - |
| Q11 | Tech Stack | 2 | auto-researchable | WebSearch |
| Q12 | Tech Stack | 2 | auto-discoverable + researchable | package.json + MCP Ref |
| Q13 | Tech Stack | 2 | auto-researchable | WebSearch |
| D1-D6 | Design Guidelines | 2 | interactive | - |
| O1-O3 | Operations | 2 | semi-auto | Dockerfile, docker-compose.yml |
| R1-R2 | Risks | 2 | interactive | - |
**Stage 0 (Context Research - BEFORE asking questions)**: ALWAYS attempt auto-discovery (Q9, Q12 from package.json/Dockerfile), ALWAYS ask for user materials (may answer Q1-Q23), ALWAYS research best practices (Q11, Q13 via MCP Ref/WebSearch). This stage can reduce interactive questions by 20-75%.
**Stage 1 (Understand Requirements)**: Ask REMAINING questions from Q1-Q3, Q5-Q8 that were NOT answered in Stage 0. Skip questions already extracted from materials.
**Stage 2 (Research & Design)**: Ask REMAINING questions from Q10, D1-D6, O1-O3, R1-R2. Questions Q9, Q11, Q12, Q13 likely already answered in Stage 0 (auto-discovery + research).
---
## Category 1: Requirements (3 questions)
### Q1: What are the high-level technical acceptance criteria?
**Why important**: Defines what "done" looks like from a technical perspective.
**Example answer**: "Users can register via JWT auth, search products with <500ms latency, complete checkout with Stripe payment webhook handling"
### Q2: What is the Minimum Viable Product (MVP) from a technical standpoint?
**Why important**: Defines Phase 1 technical scope and fastest path to functional system.
**Example answer**: "REST API with auth, CRUD for products, shopping cart in Redis, Stripe payment integration, PostgreSQL database"
### Q3: Are all functional requirements technically defined and agreed?
**Why important**: Prevents mid-project requirement discovery and scope changes.
**Example answer**: "Yes, 15 functional requirements documented with IDs (FR-UM-001: User Registration, FR-PM-001: Product Listing, etc.) and technical acceptance criteria"
---
## Category 2: Scope (4 questions)
### Q5: What is technically IN SCOPE?
**Why important**: Defines technical boundaries and prevents misunderstandings about what will be built.
**Example answer**: "Microservices architecture (Product, Order, Payment services), PostgreSQL + Redis, REST API, JWT auth, Stripe integration, AWS ECS deployment"
### Q6: What is technically OUT OF SCOPE?
**Why important**: Manages expectations and prevents technical feature creep.
**Example answer**: "No mobile native apps (web-responsive only), no AI/ML recommendations, no cryptocurrency payments, no GraphQL (REST only), no Kubernetes (ECS Fargate only)"
### Q7: Where are the technical boundaries and integration points?
**Why important**: Clarifies interfaces with external systems and services.
**Example answer**: "External APIs: Stripe (payments), SendGrid (emails), AWS S3 (images). Internal: API Gateway routes to 4 microservices, Redis Pub/Sub for events"
### Q8: Who are the technical user roles and what are their permissions?
**Why important**: Defines authentication and authorization requirements.
**Example answer**: "3 roles: Customer (browse, cart, checkout), Vendor (manage own products, view sales), Admin (platform config, user management)"
---
## Category 3: Technology Stack (5 questions)
### Q9: What technology decisions have already been made?
**Why important**: Identifies constraints and pre-existing technical commitments.
**Example answer**: "Must use: AWS (company standard), PostgreSQL (existing DBA expertise), Node.js (team skillset). Cannot use: MongoDB (no in-house experience)"
### Q10: What are the hard technical constraints?
**Why important**: Defines non-negotiable limitations that affect architecture.
**Example answer**: "Must deploy to AWS us-east-1 (company policy), must comply with PCI DSS Level 1 (no card storage), cannot use Kubernetes (team lacks experience - use ECS Fargate), must integrate with legacy SOAP API (blocking dependency), cannot use serverless (compliance restrictions)"
### Q11: What architectural patterns will be used?
**Why important**: Defines overall system structure and design approach.
**Example answer**: "Microservices architecture (4 services), Event-Driven communication (Redis Pub/Sub), REST API, Stateless services for horizontal scaling"
### Q12: What libraries and frameworks will be used?
**Why important**: Defines technical stack and team training needs.
**Example answer**: "Frontend: React 18 + Next.js 14 + Tailwind CSS. Backend: Node.js 20 + Express + Prisma ORM. Testing: Jest + Supertest + Playwright"
### Q13: What integrations with existing systems are required?
**Why important**: Identifies dependencies and integration complexity.
**Example answer**: "Integrate with: Legacy inventory system (SOAP API), Stripe (REST API), SendGrid (REST API), AWS S3 (SDK), existing user database (read-only PostgreSQL replica)"
---
## Category 4: Design Guidelines (6 questions)
### D1: What typography and color system should be used?
**Why important**: Defines visual consistency and brand identity for frontend projects.
**Example answer**: "Primary font: Inter (body), Poppins (headings). Colors: Primary #FF6B35 (orange), Secondary #004E89 (blue), Accent #1A936F (teal). WCAG 2.1 AA contrast ratios (4.5:1 text)"
### D2: What component library and UI patterns should be implemented?
**Why important**: Ensures consistent user experience and speeds up development.
**Example answer**: "Buttons: Primary/Secondary/Text variants. Forms: Input fields with validation states. Cards: Default/Hover/Interactive. Modals: Backdrop + centered content. Tables: Sortable headers + pagination"
### D3: What are the responsive breakpoints?
**Why important**: Defines how UI adapts across devices.
**Example answer**: "Mobile (<768px): 1-column stacked, Tablet (768-1024px): 2-column grid, Desktop (>1024px): 3-column grid + sidebar. Min tap target: 44x44px"
### D4: What accessibility standards must be met?
**Why important**: Ensures inclusive design for users with disabilities.
**Example answer**: "WCAG 2.1 Level AA compliance: Keyboard navigation (all features), Screen reader support (ARIA labels), Color contrast 4.5:1 (text), Focus indicators (ring-2 ring-primary)"
### D5: What branding and imagery guidelines apply?
**Why important**: Maintains consistent brand identity across the platform.
**Example answer**: "Logo: Min 32px height, clear space equals logo height. Hero images: 16:9 aspect ratio, min 1920x1080px. Stock photos: Professional, diverse, authentic (no clichés)"
### D6: What design system or inspiration should be referenced?
**Why important**: Provides design direction and accelerates UI development.
**Example answer**: "Primary reference: Airbnb Design System (professional, user-friendly). Secondary influences: Material Design (components), Tailwind CSS (utility-first), Carbon Design (enterprise patterns)"
---
## Category 5: Operations (3 questions)
### O1: What is the development environment setup?
**Why important**: Defines how developers run the project locally.
**Example answer**: "Docker Compose with 5 services: app (Node.js), db (PostgreSQL), cache (Redis), queue (RabbitMQ), nginx (reverse proxy). Commands: `docker compose up -d`, `docker compose exec app npm run migrate`"
### O2: What are the deployment procedures?
**Why important**: Defines how code reaches production safely.
**Example answer**: "CI/CD: GitHub Actions → Build Docker image → Push to ECR → Deploy to ECS Fargate (rolling update). Environments: Dev (auto-deploy main), Staging (manual approval), Production (manual approval + rollback plan)"
### O3: What monitoring and troubleshooting tools are used?
**Why important**: Enables rapid incident detection and resolution.
**Example answer**: "Logs: CloudWatch Logs (centralized). Metrics: CloudWatch + Grafana dashboards (latency, errors, throughput). Alerts: PagerDuty (>5% error rate, p95 >500ms). SSH: Bastion host access for production debugging"
---
## Category 6: Technical Risks (2 questions)
### R1: What are the key technical risks?
**Why important**: Identifies potential technical failures that need mitigation.
**Example answer**: "Risk 1: Stripe outage blocks transactions (mitigation: retry logic + queue). Risk 2: Database becomes bottleneck (mitigation: read replicas + Redis caching). Risk 3: Microservice network failures (mitigation: circuit breakers + timeouts)"
### R2: What are the critical technical dependencies?
**Why important**: Identifies external factors that could block or delay development.
**Example answer**: "Hard dependencies: AWS account approval (1 week), Stripe merchant account (2 weeks), Legacy API documentation (blocking integration). Team dependencies: 1 senior Node.js dev (key person risk)"
---
## Question Priority Levels
All 23 questions are **MUST-ANSWER** for complete technical documentation. Some questions (D1-D6) are frontend-specific and can be skipped for backend-only or API-only projects.
---
## How to Use This Document
**IMPORTANT**: Follow Priority Order (Context First, Questions Last) defined above.
1. **Stage 0 - Context Research (Phase 1)**:
- **1.2 Auto-Discovery**: Use Glob to find package.json/Dockerfile/docker-compose.yml → Extract Q9, Q12
- **1.3 User Materials**: ALWAYS ask "Do you have materials to review?" → Read and extract Q1-Q23
- **1.4 Research**: Use MCP Ref for Q12 (2025 versions), WebSearch for Q11 (patterns), Q13 (integrations)
- **Track**: Mark which questions answered in Stage 0
2. **Stage 1-2 - Interactive Questions (Phase 2)**:
- **Review**: Display "Already gathered: X/23 questions" to user
- **Ask ONLY remaining**: Skip questions answered in Stage 0
- **Batch questions**: Show progress "Category X of 6 (asking Y remaining questions)"
- **Capture Answers**: Record with question IDs for traceability
3. **Map to Documents**: Use answers (from Stage 0 or Stage 1-2) to populate:
- `requirements.md` ← Q1, Q3
- `architecture.md` ← Q5, Q6, Q7, Q9, Q10, Q11, Q12, Q13
- `tech_stack.md` ← Q9, Q10, Q11, Q12
- `api_spec.md` ← Q8, Q13
- `database_schema.md` ← Q9, Q12
- `design_guidelines.md` ← D1-D6
- `runbook.md` ← O1-O3
4. **Validate Completeness**: Ensure all relevant questions have clear answers (skip D1-D6 for backend-only projects)
5. **Iterate if Needed**: If answers are unclear or incomplete, ask follow-up questions
---
## Example Discovery Flow (Context-First Approach)
**Stage 0 - Context Research (BEFORE asking questions)**
**Step 1: Auto-Discovery**
```
Assistant: "Starting context research...
✓ Auto-discovered from package.json:
- Q9: Node.js 20, React 18
- Q12: Express, Prisma ORM, PostgreSQL, Jest, Tailwind CSS
✓ Auto-discovered from Dockerfile:
- Q9: Production runtime: Node.js 20 Alpine
```
**Step 2: Request User Materials**
```
Assistant: "Do you have existing materials I should review before asking questions?
Examples: design documents, technical specifications, requirements docs, legacy system documentation, architectural diagrams, API contracts."
User: "Yes, here's our design doc and technical spec."
```
**Step 3: Extract from Materials**
```
Assistant: "Reading materials...
✓ Extracted from design doc:
- Q1: Acceptance criteria defined (user registration, product search <500ms, Stripe checkout)
- Q5: In scope (microservices, PostgreSQL, REST API, JWT auth, Stripe, AWS ECS)
- Q6: Out of scope (no mobile apps, no AI/ML, no cryptocurrency, no GraphQL, no Kubernetes)
- Q7: Integrations: Stripe (payments), SendGrid (emails), AWS S3 (images)
- D1-D6: Full design system documented
✓ Extracted from technical spec:
- Q3: All functional requirements defined with IDs (15 requirements)
- Q10: Hard constraints (AWS us-east-1, PCI DSS Level 1, no serverless)
- Q11: Microservices architecture
- R1-R2: Technical risks and dependencies documented
Total extracted: 18/23 questions"
```
**Step 4: Research Best Practices**
```
Assistant: "Researching 2025 best practices...
✓ Researched via MCP Ref:
- Q12: Verified 2025 versions (Express 5.0, Prisma 6.0, Jest 30.0, Tailwind 4.0)
✓ Researched via WebSearch:
- Q11: Microservices best practices 2025 (event-driven, API Gateway patterns)
- Q13: Stripe API 2025 best practices (webhook security, idempotency)
Total gathered in Stage 0: 21/23 questions"
```
**Stage 1-2 - Interactive Questions (ONLY remaining)**
**Batch 1 - Remaining Questions**
```
Assistant: "✓ Context Research complete!
Information already gathered (21/23 questions):
- Auto-discovered: Q9, Q12 (from package.json/Dockerfile)
- Extracted from materials: Q1, Q3, Q5, Q6, Q7, Q10, Q11, D1-D6, R1-R2
- Researched: Q11, Q12, Q13
Remaining questions: 2 questions
Category 1 of 6: Requirements (asking 1 remaining question)
Q2: What is the Minimum Viable Product (MVP) from a technical standpoint?
Category 2 of 6: Scope (asking 1 remaining question)
Q8: Who are the technical user roles and what are their permissions?
Please provide your answers."
```
---
**Key Insight**: Context-first approach reduced interactive questions from 23 → 2 (91% reduction), saving significant user time and ensuring data accuracy from authoritative sources.
---
**Version:** 4.0.0 (MAJOR: Added Priority Order and Stage 0 Context Research)
**Last Updated:** 2025-11-17
**Changes from v3.0.0:**
- Added "Priority Order: Context First, Questions Last" section at top
- Added Stage 0 (Context Research) before Stage 1-2
- Updated "Question Metadata" to "3-Stage Discovery"
- Updated Stage descriptions to emphasize REMAINING questions only
- Updated "How to Use This Document" with Stage 0 workflow
- Updated examples to show context-first approach (91% question reduction)
- Clarified that interactive questions are LAST RESORT

120
skills/ln-114-project-docs-creator/references/guides/examples.md Normal file
View File

@@ -0,0 +1,120 @@
# Example Usage
This document provides detailed examples of using the project-documentation-creator skill in different scenarios.
## Example 1: New Project with Materials
**User Request**:
```
"I want to create technical documentation for an existing Node.js e-commerce API"
```
**Skill Response (Phase 1)**:
```
"I'll help you create comprehensive technical documentation.
1. What type of project is this? → web app, API
2. Is this a new project, rewrite, or enhancement? → existing
```
**Skill Response (Phase 2)**:
```
"Do you have project materials to analyze? (files, diagrams, docs, code)"
User: "Yes, I have package.json, Dockerfile, and docker-compose.yml"
"Analyzing project materials..."
✓ Analyzed project materials
**Detected**:
- Runtime: Node.js 20 LTS
- Framework: Express 4.18
- Database: PostgreSQL 15 (from docker-compose.yml)
- Cache: Redis 7.2 (from docker-compose.yml)
- ORM: Prisma 5.6 (from package.json)
**Pre-populated**: Q9 (partial), Q12 (partial)
"Let's proceed to Stage 1: Understanding Requirements."
```
**Skill Response (Phase 3, Stage 1)**:
```
"Stage 1: Understanding Requirements - Category 1 of 2: Requirements
Q1: What are the high-level technical acceptance criteria?
Q2: What is the Minimum Viable Product (MVP) from a technical standpoint?
Q3: Are all functional requirements technically defined?
Please answer these questions."
```
**Skill Response (Phase 3, Stage 2)**:
```
"Stage 1 complete! Research best practices automatically? (Y/N)"
User: "Y"
"Researching 2025 best practices for your e-commerce API...
**Researched Technology Stack**:
**Runtime**: Node.js 20 LTS (detected, confirmed latest)
**Framework**: Express 4.18 → Recommend upgrade to 4.19 (latest stable, security fixes)
**Database**: PostgreSQL 15 → Recommend PostgreSQL 16 (Sep 2023, 5-year support, performance improvements)
**ORM**: Prisma 5.6 → Recommend Prisma 5.7 (latest stable, bug fixes)
**Cache**: Redis 7.2 (confirmed latest stable)
**Architectural Pattern**: RESTful API with Layered Architecture (Controller → Service → Repository)
Rationale: Matches your current Express setup, clear separation of concerns, testable
**Additional Libraries**:
- Validation: Zod 3.22 (type-safe schemas)
- Testing: Jest 29 + Supertest 6 (unit + integration)
- Security: helmet 7 + express-rate-limit 7
Do you accept these recommendations? (Y/N/Modify)"
```
**After All Phases Complete**:
```
"Technical documentation generation complete!
**Generated Files**:
- docs/project/requirements.md (15 FR)
- docs/project/architecture.md (with C4 diagrams)
- docs/project/technical_specification.md (includes auto-generated Dockerfile + docker-compose.yml)
- docs/project/adrs/ (5 ADRs: Express, PostgreSQL, Prisma, Redis, REST API)
**Next Steps**:
1. Review the generated documentation with your technical team
2. Use these documents as input for epic-creator to start creating Epics
Would you like to review any specific document or make adjustments?"
```
## Example 2: New Project without Materials
**User Request**:
```
"I want to create technical documentation for a new mobile app project"
```
**Skill Response**:
```
"I'll help you create comprehensive technical documentation.
1. What type of project is this? → mobile app
2. Is this a new project, rewrite, or enhancement? → new project
Do you have project materials to analyze? (files, diagrams, docs, code)"
User: "No"
"Let's begin Stage 1: Understanding Requirements."
```
*[Proceeds with fully interactive Q1-Q19 dialog, with automatic research option for Q9, Q11-Q13]*
---
**Version:** 2.0.0
**Last Updated:** 2025-01-31

285
skills/ln-114-project-docs-creator/references/guides/template_mappings.md Normal file
View File

@@ -0,0 +1,285 @@
# Template Mappings Reference
This document details how collected answers from Phase 2 (Core Documents Generation) map to specific sections in the 7 generated documentation templates.
## Document 1: requirements.md
**Template File**: `references/templates/requirements_template.md`
**Structure**:
- Functional Requirements (FR) ONLY organized by feature groups
- NO Non-Functional Requirements (NFR removed per project policy)
- Each requirement includes: ID, Description, Priority (MoSCoW), Acceptance Criteria
**Key Mappings**:
| Template Section | Source Questions | Notes |
|-----------------|------------------|-------|
| Section 1.2 Scope | Q1 | High-level technical acceptance criteria |
| Section 2.1 Product Perspective | Q2 | MVP technical scope |
| Section 3 FR by feature groups | Q1, Q2, Q3 | Organize functional requirements by user-facing features |
| Section 5 Constraints | Q10 | Technical and regulatory constraints |
**Format Example**:
```markdown
### FR-AUTH-001: User Registration
**Priority**: MUST
**Description**: Users can register with email and password
**Acceptance Criteria**:
- Email validation (RFC 5322)
- Password strength requirements (min 12 chars, uppercase, lowercase, number, symbol)
- Confirmation email sent within 5 seconds
```
---
## Document 2: architecture.md
**Template File**: `references/templates/architecture_template.md`
**Structure**:
- 11 sections following arc42 (simplified) + C4 Model
- Includes Mermaid diagrams (C4 Context, Container, Component)
- NO Deployment diagrams (moved to runbook.md)
**Key Mappings**:
| Template Section | Source Questions | Notes |
|-----------------|------------------|-------|
| Section 1.1 Requirements Overview | Q1, Q2 | Brief summary linking to requirements.md |
| Section 1.2 Quality Goals | R1 | Top 3-5 quality attributes (performance, security, scalability) |
| Section 2 Constraints | Q10 | Technical, organizational, regulatory constraints |
| Section 3.1 Business Context | Q5, Q6 | External actors and business boundaries |
| Section 3.2 Technical Context | Q7, Q13 | External systems, integrations, interfaces |
| Section 4.1 Technology Decisions | Q9, Q11, Q12 | High-level tech choices with ADR links |
| Section 4.2 Top-Level Decomposition | Q11 | Architecture pattern (layered, microservices, etc.) |
| Section 8 ADRs | Q9, Q11, Q12 | List of all ADR links |
| Section 10 Risks | R2 | Known technical risks and mitigation |
**Diagram Mappings**:
| Diagram Type | Generated From | Purpose |
|-------------|---------------|---------|
| C4 Context | Q7 (boundaries), Q13 (integrations) | System + external actors/systems |
| C4 Container | Q11 (architecture), Q9 (database/cache) | Frontend, Backend, Database, Cache, Queue |
| C4 Component | Q11 (pattern), Q12 (frameworks) | API application breakdown (controllers, services, repositories) |
**Note**: Deployment diagrams removed (now in runbook.md). Quality Goals derived from R1 (risks), NOT from NFR questions.
---
## Document 3: tech_stack.md
**Template File**: `references/templates/tech_stack_template.md`
**Structure**:
- 4 sections: Overview, Technology Stack table, Docker configuration, Naming conventions
- NO API endpoints, NO database schema (those in separate docs)
**Key Mappings**:
| Template Section | Source Questions | Notes |
|-----------------|------------------|-------|
| Section 2.1 Stack Overview Table | Q9, Q11, Q12 | Detailed version table with rationale and ADR links |
| Section 3.1 Dockerfile | Q9, Q12 (auto-discovered) | Auto-generated multi-stage Dockerfile |
| Section 3.2 docker-compose.yml | Q9, Q12 (auto-discovered) | Auto-generated from package.json + researched versions |
| Section 3.3 docker-compose.test.yml | Q9, Q12 | Test environment configuration |
| Section 4 Naming Conventions | Q8 | File structure, naming patterns |
**Stack Table Format**:
```markdown
| Layer | Technology | Version | Rationale | ADR |
|-------|-----------|---------|-----------|-----|
| Frontend | Next.js | 14.0 | SSR for SEO, team expertise | ADR-001 |
| Backend | Node.js | 20 LTS | JavaScript fullstack, async I/O | ADR-002 |
| Database | PostgreSQL | 16 | ACID, JSON support, maturity | ADR-003 |
```
**Auto-Discovery**: Phase 1.3a extracts Q9 (runtime versions) and Q12 (frameworks) from package.json/Dockerfile before asking user.
---
## Document 4: api_spec.md *(conditional: API/Backend projects only)*
**Template File**: `references/templates/api_spec_template.md`
**Structure**:
- 6 sections: Overview, Authentication, API Endpoints, Request/Response schemas, Error Codes, Rate Limiting
- OpenAPI 3.0 compatible structure
**Key Mappings**:
| Template Section | Source Questions | Notes |
|-----------------|------------------|-------|
| Section 2 Authentication | Q11, Q12 | JWT/OAuth2/API keys implementation |
| Section 3 API Endpoints | Q1, Q3 (derived) | RESTful endpoints derived from functional requirements |
| Section 5 Error Codes | - | Standard error code taxonomy |
| Section 6 Rate Limiting | Q10 | API rate limits from constraints |
**Endpoint Table Format**:
```markdown
| Method | Endpoint | Description | Auth Required | Request Body | Response |
|--------|----------|-------------|---------------|--------------|----------|
| POST | /auth/register | Register new user | No | RegisterDTO | UserDTO |
| GET | /products | List products | No | - | ProductDTO[] |
| POST | /orders | Create order | Yes | OrderDTO | OrderDTO |
```
**Auto-Generation**: Endpoints derived from FR requirements in Q1, Q3 (e.g., "User Registration" → POST /auth/register).
---
## Document 5: database_schema.md *(conditional: projects with database)*
**Template File**: `references/templates/database_schema_template.md`
**Structure**:
- 8 sections: Overview, ER Diagram, Data Dictionary (tables), Indexes, Migrations, Relationships, Constraints, Seed Data
- Mermaid ER diagrams
**Key Mappings**:
| Template Section | Source Questions | Notes |
|-----------------|------------------|-------|
| Section 2 ER Diagram | Q3 (derived) | Entities + relationships from functional requirements |
| Section 3 Data Dictionary | Q3 (derived) | Table definitions with columns, types, constraints |
| Section 4 Indexes | Q3, Q9 | Performance optimization indexes |
| Section 5 Migrations | Q9 | Migration strategy (Prisma/TypeORM/Alembic) |
| Section 8 Seed Data | Q3 | Sample data for development |
**ER Diagram Example**:
```mermaid
erDiagram
USERS ||--o{ ORDERS : places
ORDERS ||--|{ ORDER_ITEMS : contains
PRODUCTS ||--o{ ORDER_ITEMS : "ordered in"
USERS {
uuid id PK
string email UK
string password_hash
timestamp created_at
}
```
**Auto-Generation**: Entities derived from Q3 analysis (e.g., "User Registration" → USERS table, "Product Catalog" → PRODUCTS table).
---
## Document 6: design_guidelines.md *(conditional: Frontend/Full-stack projects only)*
**Template File**: `references/templates/design_guidelines_template.md`
**Structure**:
- 6 sections: Overview, Core Design Elements (typography, colors, spacing, components), Accessibility, Responsive Design, Brand Assets, Design Tokens
- Based on WCAG 2.1 Level AA standards
**Key Mappings**:
| Template Section | Source Questions | Notes |
|-----------------|------------------|-------|
| Section 2.1 Typography | D1 | Font families, sizes, weights, line heights |
| Section 2.2 Color System | D1 | Primary/secondary/semantic colors with hex codes |
| Section 2.3 Spacing System | D1, D3 | 8px base grid, spacing scale (4, 8, 12, 16, 24, 32, 48, 64) |
| Section 2.4 Component Library | D2 | Buttons, Forms, Cards, Modals with Tailwind/MUI classes |
| Section 3 Accessibility | D4 | WCAG compliance, ARIA labels, keyboard navigation |
| Section 4 Responsive Design | D3 | Breakpoints (mobile, tablet, desktop) |
| Section 5 Brand Assets | D5 | Logo usage, imagery guidelines |
| Section 6 Design Tokens | D6 | CSS variables or design system reference |
**Component Example**:
```markdown
#### Buttons
| Variant | Classes | Usage |
|---------|---------|-------|
| Primary | bg-primary text-white hover:bg-primary-dark px-6 py-3 rounded-lg | Primary CTAs |
| Secondary | bg-secondary text-gray-800 hover:bg-secondary-dark px-6 py-3 rounded-lg | Secondary actions |
```
**Skipped for**: Backend-only projects (no frontend).
---
## Document 7: runbook.md *(conditional: Docker-based projects)*
**Template File**: `references/templates/runbook_template.md`
**Structure**:
- 9 sections covering ALL environments: local development, testing, production operations
- Includes Docker commands, troubleshooting, SSH access, deployment procedures
**Key Mappings**:
| Template Section | Source Questions | Notes |
|-----------------|------------------|-------|
| Section 2.1 Required Tools | O1 (auto-discovered) | Docker, Docker Compose, Node.js, Git versions |
| Section 3 Local Development | O1, Q9 (auto-discovered) | Docker commands extracted from docker-compose.yml |
| Section 4 Testing | O1 | Test commands (unit, integration, e2e) |
| Section 5 Build & Deployment | O2 | Production build and deployment procedures |
| Section 6 Production Operations | O2, O3 | SSH access, health checks, monitoring, logs |
| Section 7 Troubleshooting | O3 | Common issues and resolutions |
| Appendix A | O1 (auto-discovered) | Environment variables from .env.example |
**Docker Commands Example**:
```bash
# Start all services
docker compose up -d
# Rebuild after code changes
docker compose down
docker compose build --no-cache app
docker compose up -d
# View logs
docker compose logs -f app
```
**Auto-Discovery**: Docker commands, environment variables, and service names extracted from Dockerfile and docker-compose.yml in Phase 1.3a.
---
## Template Placeholder Format
All templates use explicit placeholder mapping with comments for traceability:
```markdown
**Technology Stack:** {{TECHNOLOGY_STACK}}
<!-- From Q9: What database technology will you use? (auto-discovered from package.json) -->
**Architecture Pattern:** {{ARCHITECTURE_PATTERN}}
<!-- From Q11: What architectural patterns will be used? (auto-researched via WebSearch) -->
**Color System:** {{COLOR_SYSTEM}}
<!-- From D1: What typography and color system should be used? -->
**Docker Commands:** {{DOCKER_COMMANDS}}
<!-- From O1: What is the development environment setup? (auto-discovered from docker-compose.yml) -->
```
This format allows clear traceability from questions to documentation sections. Auto-discovery annotations indicate when data is extracted automatically in Phase 1.3a.
---
## Appendix: ADRs (Auto-Generated)
**Note**: ADRs are still auto-generated as part of the documentation suite, but are NOT one of the 7 main documents.
**Template File**: `references/templates/adr_template.md`
**Generated ADRs** (3-5 per project):
| ADR | Title | Source Questions | When Generated |
|-----|-------|------------------|---------------|
| ADR-001 | Frontend Framework Choice | Q11, Q12 | If frontend framework specified |
| ADR-002 | Backend Framework Choice | Q11, Q12 | Always (every project has backend) |
| ADR-003 | Database Choice | Q9 | If database specified |
| ADR-004 | Additional Technology 1 | Q12 | If significant library chosen (ORM, cache, queue) |
| ADR-005 | Additional Technology 2 | Q12 | If multiple significant choices made |
**Format**: Michael Nygard's ADR format (Context, Decision, Rationale, Consequences, Alternatives Considered)
**Location**: `docs/reference/adrs/adr-NNN-*.md`
---
**Version:** 2.0.0 (BREAKING: Updated for 7-document structure. Added tech_stack, api_spec, database_schema, design_guidelines, runbook mappings. Removed NFR mappings. Updated question IDs: Q1-Q13, D1-D6, O1-O3, R1-R2.)
**Last Updated:** 2025-11-16

41
skills/ln-114-project-docs-creator/references/guides/troubleshooting.md Normal file
View File

@@ -0,0 +1,41 @@
# Troubleshooting Guide
This document provides solutions to common issues when using the x-docs-creator skill.
## Issue 1: User Doesn't Know Answers
**Problem**: User doesn't know answers to some technical questions during Phase 3 discovery.
**Solution**:
- Mark questions as "TBD" and flag for follow-up
- Generate documents with placeholders (e.g., `{{TODO: Define performance requirements}}`)
- Skill can be re-run later to update documentation once answers are available
- Documents remain valid with TBD placeholders for initial planning
## Issue 2: Project Too Small
**Problem**: Project is very small (1-2 person team, simple app) and 19 questions seem excessive.
**Solution**:
- Skip optional questions that don't apply to small projects
- Generate minimal viable technical documentation:
- Requirements document (simplified FR only - critical functional requirements)
- Simplified Architecture (basic tech stack + deployment diagram)
- Skip detailed technical specifications and ADRs if not needed
- Focus on Q1-Q8 (requirements + scope) as minimum viable documentation
## Issue 3: Auto-Research Returns Outdated Technologies
**Problem**: Phase 3 Stage 2 auto-research recommends outdated or deprecated technologies.
**Solution**:
- **Verify Research Date**: Skill uses current date (2025) for research
- **Check MCP Ref Results**: Review specific library documentation returned
- **Manually Verify**: Cross-check recommendations with official docs
- **Override if Needed**: Select "Modify" option to override recommendations
- **Report Issue**: If persistent, check skill version and update
---
**Version:** 2.0.0
**Last Updated:** 2025-01-31

750
skills/ln-114-project-docs-creator/references/questions.md Normal file
View File

@@ -0,0 +1,750 @@
# Project Documentation Questions
**Purpose:** Define what each section of project documentation should answer.
**Format:** Question → Expected Answer → Validation Heuristics → Auto-Discovery → MCP Ref Hints
---
## Table of Contents
| Document | Questions | Auto-Discovery | Priority | Line |
|----------|-----------|----------------|----------|------|
| [requirements.md](#docsprojectrequirementsmd) | 1 | Low | Critical | L30 |
| [architecture.md](#docsprojectarchitecturemd) | 11 | High | Critical | L92 |
| [tech_stack.md](#docsprojecttechstackmd) | 4 | High | High | L394 |
| [api_spec.md](#docsprojectapispecmd) | 2 | Medium | High | L495 |
| [database_schema.md](#docsprojectdatabaseschemamd) | 2 | High | High | L560 |
| [design_guidelines.md](#docsprojectdesignguidelinesmd) | 3 | Low | Medium | L625 |
| [runbook.md](#docsprojectrunbookmd) | 3 | High | Critical | L715 |
**Priority Legend:**
- **Critical:** Must answer all questions (requirements, architecture, runbook)
- **High:** Strongly recommended (tech_stack, api_spec, database_schema)
- **Medium:** Optional for some project types (design_guidelines - frontend only)
**Auto-Discovery Legend:**
- **None:** No auto-discovery needed (use template as-is)
- **Low:** 1-2 questions need auto-discovery
- **Medium:** 50% questions need auto-discovery
- **High:** Most/all questions need auto-discovery
---
<!-- DOCUMENT_START: docs/project/requirements.md -->
## docs/project/requirements.md
**File:** docs/project/requirements.md (functional requirements ONLY)
**Target Sections:** Functional Requirements
**Rules for this document:**
- ISO/IEC/IEEE 29148:2018 compliant
- FR-XXX-NNN identifiers for all requirements
- MoSCoW prioritization (MUST/SHOULD/COULD/WON'T)
- User stories or acceptance criteria format
---
<!-- QUESTION_START: 1 -->
### Question 1: What functionality must the system provide?
**Expected Answer:** Numbered list of functional requirements with FR-XXX-NNN identifiers, MoSCoW priorities, user stories/acceptance criteria
**Target Section:** ## Functional Requirements
**Validation Heuristics:**
- ✅ Has FR-XXX identifiers (e.g., FR-001, FR-USR-001)
- ✅ Has MoSCoW labels (MUST/SHOULD/COULD/WON'T)
- ✅ Length > 100 words
- ✅ Has numbered list or table
**Auto-Discovery:**
- Check: package.json → "description" for feature clues
- Check: README.md for feature mentions
- Check: existing docs for use case descriptions
**MCP Ref Hints:**
- Research: "functional requirements best practices"
- Research: "MoSCoW prioritization method"
<!-- QUESTION_END: 1 -->
<!-- DOCUMENT_END: docs/project/requirements.md -->
---
<!-- DOCUMENT_START: docs/project/architecture.md -->
## docs/project/architecture.md
**File:** docs/project/architecture.md (arc42 framework with C4 Model)
**Target Sections:** 11 sections (Introduction and Goals → Glossary)
**Rules for this document:**
- ISO/IEC/IEEE 42010:2022 compliant
- arc42 framework structure (11 sections)
- C4 Model diagrams (Context, Container, Component)
- Mermaid syntax for all diagrams
---
<!-- QUESTION_START: 3 -->
### Question 3: What are the key quality goals and stakeholders?
**Expected Answer:** Requirements overview summary, 5 quality goals with metrics (Performance, Security, Scalability, Reliability, Maintainability), stakeholders table with roles
**Target Section:** ## 1. Introduction and Goals
**Validation Heuristics:**
- ✅ Has subsections 1.1, 1.2, 1.3
- ✅ Quality goals have measurable metrics
- ✅ Stakeholders table has roles and expectations
- ✅ References requirements.md
**Auto-Discovery:**
- Check: architecture.md → Section 1.2 Quality Goals (derived from risks R1)
- Check: package.json → "author" for stakeholder hints
**MCP Ref Hints:**
- Research: "arc42 quality goals"
- Research: "ISO 25010 quality attributes"
<!-- QUESTION_END: 3 -->
---
<!-- QUESTION_START: 4 -->
### Question 4: What technical and organizational constraints exist?
**Expected Answer:** Technical constraints (languages, databases, cloud providers), organizational constraints (team size, compliance), conventions (code style, testing standards)
**Target Section:** ## 2. Constraints
**Validation Heuristics:**
- ✅ Has subsections 2.1 (Technical), 2.2 (Organizational), 2.3 (Conventions)
- ✅ Mentions specific technologies
- ✅ Lists compliance requirements (GDPR, HIPAA, etc.)
**Auto-Discovery:**
- Check: package.json → "dependencies" for tech stack
- Check: .eslintrc, .prettierrc for code style conventions
- Check: tsconfig.json, jest.config.js for conventions
**MCP Ref Hints:**
- Research: "architecture constraints examples"
<!-- QUESTION_END: 4 -->
---
<!-- QUESTION_START: 5 -->
### Question 5: What are the system boundaries and external interfaces?
**Expected Answer:** Business context (actors, external systems), technical context (protocols, data formats), C4 Context diagram (Mermaid)
**Target Section:** ## 3. Context and Scope
**Validation Heuristics:**
- ✅ Has subsections 3.1 (Business Context), 3.2 (Technical Context)
- ✅ Has Mermaid code block with C4 Context diagram
- ✅ Lists external systems and protocols
**Auto-Discovery:**
- Check: package.json → "dependencies" for external service clients (stripe, twilio, aws-sdk)
- Check: .env.example for API_URL, DATABASE_URL (external systems)
**MCP Ref Hints:**
- Research: "C4 model context diagram examples"
- Research: "system context best practices"
<!-- QUESTION_END: 5 -->
---
<!-- QUESTION_START: 6 -->
### Question 6: What are the top-level architectural decisions?
**Expected Answer:** Technology decisions table (Frontend, Backend, Database with rationale and ADR links), top-level decomposition approach (Layered/Microservices/Modular), approach to quality goals
**Target Section:** ## 4. Solution Strategy
**Validation Heuristics:**
- ✅ Has subsections 4.1 (Technology Decisions), 4.2 (Top-level Decomposition), 4.3 (Quality Goals Approach)
- ✅ Technology table references ADRs
- ✅ Explains architecture pattern choice
**Auto-Discovery:**
- Check: package.json → "dependencies" for frontend/backend frameworks
- Check: src/ directory structure:
- controllers/, services/, repositories/ → Layered architecture
- modules/, features/ → Modular architecture
- pages/, components/ → Frontend structure
**MCP Ref Hints:**
- Research: "layered architecture vs microservices"
- Research: "architecture patterns comparison 2024"
<!-- QUESTION_END: 6 -->
---
<!-- QUESTION_START: 7 -->
### Question 7: How is the system decomposed into components?
**Expected Answer:** C4 diagrams (Level 1 System Context, Level 2 Container, Level 3 Component), key components table, infrastructure layer components
**Target Section:** ## 5. Building Block View
**Validation Heuristics:**
- ✅ Has subsections 5.1 (Level 1), 5.2 (Level 2), 5.3 (Level 3)
- ✅ Has 3 Mermaid C4 diagrams
- ✅ Has components table with responsibilities
**Auto-Discovery:**
- Scan: src/ directory for folders (controllers, services, repositories, components)
- Check: package.json → "main" for entry point
- Count: number of controllers, services, components
**MCP Ref Hints:**
- Research: "C4 model component diagram"
- Research: "software architecture decomposition patterns"
<!-- QUESTION_END: 7 -->
---
<!-- QUESTION_START: 8 -->
### Question 8: What are the critical runtime scenarios?
**Expected Answer:** 3-5 key scenarios with sequence diagrams (User Registration, Product Purchase, API Request Flow, etc.)
**Target Section:** ## 6. Runtime View
**Validation Heuristics:**
- ✅ Has subsections 6.1, 6.2, 6.3 (at least 3 scenarios)
- ✅ Each subsection has Mermaid sequence diagram
- ✅ Scenarios align with functional requirements
**Auto-Discovery:**
- Check: requirements.md for use cases/user stories
- Check: api_spec.md for endpoint flows
**MCP Ref Hints:**
- Research: "sequence diagram best practices"
- Research: "runtime view arc42 examples"
<!-- QUESTION_END: 8 -->
---
<!-- QUESTION_START: 9 -->
### Question 9: What concepts apply across the system?
**Expected Answer:** Crosscutting concepts for Security (Auth, Authorization, Encryption), Error Handling, Configuration Management, Data Access Pattern
**Target Section:** ## 7. Crosscutting Concepts
**Validation Heuristics:**
- ✅ Has subsections 7.1 (Security), 7.2 (Error Handling), 7.3 (Configuration), 7.4 (Data Access)
- ✅ Each subsection > 50 words
- ✅ References specific libraries/patterns
**Auto-Discovery:**
- Check: package.json → "dependencies" for auth libraries (passport, jsonwebtoken, bcrypt)
- Check: .env.example for configuration patterns
- Check: src/models or src/repositories for data access pattern
**MCP Ref Hints:**
- Research: "security architecture best practices"
- Research: "repository pattern vs active record"
- Research: "error handling patterns Node.js/Python/Go"
<!-- QUESTION_END: 9 -->
---
<!-- QUESTION_START: 10 -->
### Question 10: What are the key architecture decisions and their rationale?
**Expected Answer:** List of ADRs with links to docs/reference/adrs/, critical ADRs summary (top 3-5 decisions)
**Target Section:** ## 8. Architecture Decisions (ADRs)
**Validation Heuristics:**
- ✅ Has placeholder {{ADR_LIST}} or actual ADR links
- ✅ Has "Critical ADRs Summary" subsection
- ✅ Links to docs/reference/adrs/ directory
**Auto-Discovery:**
- Scan: docs/reference/adrs/ for *.md files
- Read: ADR titles from filenames or file headers
**MCP Ref Hints:**
- N/A (ADRs are project-specific)
<!-- QUESTION_END: 10 -->
---
<!-- QUESTION_START: 11 -->
### Question 11: What are the quality scenarios and metrics?
**Expected Answer:** Quality tree (ISO 25010 hierarchy), quality scenarios table with testable criteria (QS-1, QS-2, ...)
**Target Section:** ## 9. Quality Requirements
**Validation Heuristics:**
- ✅ Has subsections 9.1 (Quality Tree), 9.2 (Quality Scenarios)
- ✅ Quality scenarios have testable criteria
- ✅ References ISO 25010 quality model
**Auto-Discovery:**
- Check: architecture.md → Section 1.2 Quality Goals
**MCP Ref Hints:**
- Research: "ISO 25010 quality scenarios"
- Research: "quality attribute workshop methods"
<!-- QUESTION_END: 11 -->
---
<!-- QUESTION_START: 12 -->
### Question 12: What are the known risks and technical debt?
**Expected Answer:** Technical risks list with likelihood/impact, technical debt table (item, impact, plan, timeline), mitigation strategies
**Target Section:** ## 10. Risks and Technical Debt
**Validation Heuristics:**
- ✅ Has subsections 10.1 (Risks), 10.2 (Technical Debt), 10.3 (Mitigation)
- ✅ Technical debt table has timeline
- ✅ Risks have likelihood and impact ratings
**Auto-Discovery:**
- Check: package.json → "dependencies" for outdated/EOL versions (npm outdated)
- Scan: codebase for TODO/FIXME comments
- Check: .github/dependabot.yml for security alerts
**MCP Ref Hints:**
- Research: "technical debt management best practices"
- Research: "architecture risk assessment methods"
<!-- QUESTION_END: 12 -->
---
<!-- QUESTION_START: 13 -->
### Question 13: What domain terms need definition?
**Expected Answer:** Table of terms and definitions, standard C4/architecture terms (Container, Component, SSR, RBAC, JWT)
**Target Section:** ## 11. Glossary
**Validation Heuristics:**
- ✅ Has table with Term | Definition columns
- ✅ Contains standard C4/architecture terms
- ✅ Includes project-specific domain terms
**Auto-Discovery:**
- Scan: all docs for domain-specific terms (business terminology)
- Extract: technical acronyms from code (API, SSR, RBAC, JWT)
**MCP Ref Hints:**
- Research: "C4 model glossary standard terms"
<!-- QUESTION_END: 13 -->
<!-- DOCUMENT_END: docs/project/architecture.md -->
---
<!-- DOCUMENT_START: docs/project/tech_stack.md -->
## docs/project/tech_stack.md
**File:** docs/project/tech_stack.md (technology stack with versions and rationale)
**Target Sections:** Frontend Technologies, Backend Technologies, Database, Additional Technologies
**Rules for this document:**
- Technology table with Name, Version, Rationale, ADR Link
- Docker configuration (Dockerfile + docker-compose.yml)
- Version pinning and upgrade strategy
---
<!-- QUESTION_START: 14 -->
### Question 14: What frontend technologies are used and why?
**Expected Answer:** Framework name (React, Vue, Angular), version, rationale (team expertise, performance, ecosystem), key libraries
**Target Section:** ## Frontend Technologies
**Validation Heuristics:**
- ✅ Mentions framework name (React, Vue, Angular, Svelte)
- ✅ Has version number
- ✅ Has "Rationale" or "Why" explanation
- ✅ Lists key libraries (state management, routing, UI)
**Auto-Discovery:**
- Check: package.json → "dependencies" for frontend frameworks (react, vue, @angular/core, svelte)
- Extract: version numbers from package.json
- Check: package.json → react-router-dom, redux, vuex, pinia, @ngrx/store
**MCP Ref Hints:**
- Research: "[framework] latest version features 2024"
- Research: "[framework] best practices"
<!-- QUESTION_END: 14 -->
---
<!-- QUESTION_START: 15 -->
### Question 15: What backend technologies are used and why?
**Expected Answer:** Runtime (Node.js, Python, Go, Java), framework (Express, FastAPI, Gin, Spring Boot), version, rationale
**Target Section:** ## Backend Technologies
**Validation Heuristics:**
- ✅ Mentions runtime + framework
- ✅ Has version numbers
- ✅ Has rationale explanation
**Auto-Discovery:**
- Check: package.json → "dependencies" (express, fastify, koa, nestjs)
- Check: requirements.txt, pyproject.toml (fastapi, django, flask)
- Check: go.mod (gin, echo, fiber)
- Check: pom.xml, build.gradle (spring-boot)
**MCP Ref Hints:**
- Research: "[runtime] [framework] performance comparison 2024"
<!-- QUESTION_END: 15 -->
---
<!-- QUESTION_START: 16 -->
### Question 16: What database technologies are used and why?
**Expected Answer:** Database type (PostgreSQL, MongoDB, MySQL), version, rationale (ACID, JSON support, scalability)
**Target Section:** ## Database
**Validation Heuristics:**
- ✅ Mentions database name
- ✅ Has version number
- ✅ Has rationale (ACID, performance, features)
**Auto-Discovery:**
- Check: package.json → "dependencies" (pg, mongoose, mysql2, sqlite3)
- Check: docker-compose.yml for database services (postgres, mongo, mysql, redis)
- Check: requirements.txt (psycopg2, pymongo, mysql-connector)
**MCP Ref Hints:**
- Research: "[database] version features"
- Research: "PostgreSQL vs MongoDB comparison"
<!-- QUESTION_END: 16 -->
---
<!-- QUESTION_START: 17 -->
### Question 17: What other key technologies are used?
**Expected Answer:** Caching (Redis, Memcached), message queue (RabbitMQ, Kafka), search (Elasticsearch, Algolia), file storage (S3, local)
**Target Section:** ## Additional Technologies
**Validation Heuristics:**
- ✅ Lists categories with technologies
- ✅ Each technology has version and rationale
**Auto-Discovery:**
- Check: package.json → "dependencies" for all libraries (redis, ioredis, amqplib, kafkajs, @elastic/elasticsearch)
- Check: docker-compose.yml for additional services (redis, rabbitmq, elasticsearch)
**MCP Ref Hints:**
- Research: "redis vs memcached comparison"
- Research: "rabbitmq vs kafka use cases"
<!-- QUESTION_END: 17 -->
<!-- DOCUMENT_END: docs/project/tech_stack.md -->
---
<!-- DOCUMENT_START: docs/project/api_spec.md -->
## docs/project/api_spec.md
**File:** docs/project/api_spec.md (API specification - Backend/Full-stack only)
**Target Sections:** API Overview, Endpoints
**Rules for this document:**
- OpenAPI 3.0 compatible format
- RESTful/GraphQL/gRPC patterns
- Authentication and error codes documented
**Note:** This document is conditional - only validate for Backend/Full-stack projects
---
<!-- QUESTION_START: 18 -->
### Question 18: What is the API architecture and authentication?
**Expected Answer:** API type (RESTful, GraphQL, gRPC), base URL, versioning strategy (URL/header), authentication (JWT, OAuth2, API keys)
**Target Section:** ## API Overview
**Validation Heuristics:**
- ✅ Mentions API type (REST, GraphQL, gRPC)
- ✅ Has base URL or pattern
- ✅ Describes auth method (JWT, OAuth2, API keys)
- ✅ Explains versioning strategy
**Auto-Discovery:**
- Check: package.json → "dependencies" (express, @apollo/server, @grpc/grpc-js)
- Scan: src/routes/ or src/controllers/ for endpoint patterns
- Check: .env.example for API_BASE_URL, JWT_SECRET
**MCP Ref Hints:**
- Research: "REST API design best practices"
- Research: "API authentication methods comparison"
<!-- QUESTION_END: 18 -->
---
<!-- QUESTION_START: 19 -->
### Question 19: What are the available API endpoints?
**Expected Answer:** Table of endpoints (Method, Path, Description), request/response examples, error codes
**Target Section:** ## Endpoints
**Validation Heuristics:**
- ✅ Has endpoint table with Method | Path | Description
- ✅ Has request/response examples
- ✅ Documents error codes (400, 401, 403, 404, 500)
**Auto-Discovery:**
- Scan: src/routes/*.js, src/routes/*.ts for route definitions
- Check: OpenAPI/Swagger spec file if exists (openapi.yaml, swagger.json)
- Extract: HTTP methods (GET, POST, PUT, DELETE, PATCH)
**MCP Ref Hints:**
- Research: "OpenAPI specification examples"
- Research: "REST API endpoint documentation"
<!-- QUESTION_END: 19 -->
<!-- DOCUMENT_END: docs/project/api_spec.md -->
---
<!-- DOCUMENT_START: docs/project/database_schema.md -->
## docs/project/database_schema.md
**File:** docs/project/database_schema.md (database schema - conditional)
**Target Sections:** Schema Overview, Tables/Collections
**Rules for this document:**
- ER diagrams in Mermaid syntax
- Data dictionary with all tables/collections
- Relationships and constraints documented
**Note:** This document is conditional - only validate if database detected in dependencies
---
<!-- QUESTION_START: 20 -->
### Question 20: What is the database structure?
**Expected Answer:** Database type (SQL/NoSQL), schema diagram (Mermaid ERD), table/collection list
**Target Section:** ## Schema Overview
**Validation Heuristics:**
- ✅ Has Mermaid ERD diagram
- ✅ Lists all tables/collections
- ✅ Shows relationships between tables
**Auto-Discovery:**
- Check: migrations/ or schema/ directory for table definitions
- Check: src/models/ for entity definitions (Sequelize, TypeORM, Prisma, Mongoose)
- Scan: migration files for CREATE TABLE statements
**MCP Ref Hints:**
- Research: "database ERD diagram examples"
- Research: "database schema best practices"
<!-- QUESTION_END: 20 -->
---
<!-- QUESTION_START: 21 -->
### Question 21: What are the table structures and relationships?
**Expected Answer:** For each table: columns, types, constraints, relationships (foreign keys, references)
**Target Section:** ## Tables/Collections
**Validation Heuristics:**
- ✅ Has table definitions with columns and types
- ✅ Describes relationships (1:1, 1:N, N:M)
- ✅ Documents constraints (PRIMARY KEY, FOREIGN KEY, UNIQUE, NOT NULL)
**Auto-Discovery:**
- Read: migration files for detailed column definitions
- Read: model files (models/*.js, models/*.ts) for schema definitions
- Extract: foreign key relationships
**MCP Ref Hints:**
- Research: "database normalization best practices"
- Research: "SQL foreign key relationships"
<!-- QUESTION_END: 21 -->
<!-- DOCUMENT_END: docs/project/database_schema.md -->
---
<!-- DOCUMENT_START: docs/project/design_guidelines.md -->
## docs/project/design_guidelines.md
**File:** docs/project/design_guidelines.md (UI/UX design system - Frontend only)
**Target Sections:** Design System, Typography, Colors
**Rules for this document:**
- WCAG 2.1 Level AA compliant
- Design system or component library documented
- Accessibility guidelines included
**Note:** This document is conditional - only validate for Frontend/Full-stack projects
---
<!-- QUESTION_START: 22 -->
### Question 22: What is the design system or component library?
**Expected Answer:** Design system name (Material-UI, Ant Design, custom), key components, customization approach
**Target Section:** ## Design System
**Validation Heuristics:**
- ✅ Mentions design system name or "custom design system"
- ✅ Lists key components (Button, Input, Card, Modal, etc.)
- ✅ Explains customization/theming approach
**Auto-Discovery:**
- Check: package.json → "dependencies" (@mui/material, antd, chakra-ui, @headlessui/react)
- Scan: src/components/ for component library usage
**MCP Ref Hints:**
- Research: "[design system] customization guide"
- Research: "design system best practices 2024"
<!-- QUESTION_END: 22 -->
---
<!-- QUESTION_START: 23 -->
### Question 23: What fonts and text styles are used?
**Expected Answer:** Font families (primary, secondary), font sizes (headings, body, small), font weights
**Target Section:** ## Typography
**Validation Heuristics:**
- ✅ Lists font families
- ✅ Has size/weight specifications
- ✅ Shows typography scale (h1-h6, body, small)
**Auto-Discovery:**
- Check: src/styles/ or CSS files for font definitions
- Check: package.json → "dependencies" for font libraries (@fontsource/*, next/font)
- Check: tailwind.config.js for fontFamily settings
**MCP Ref Hints:**
- Research: "typography scale best practices"
- Research: "web font pairing guide"
<!-- QUESTION_END: 23 -->
---
<!-- QUESTION_START: 24 -->
### Question 24: What is the color palette?
**Expected Answer:** Primary, secondary, accent colors (hex codes), neutral colors (grays), semantic colors (success, error, warning, info)
**Target Section:** ## Colors
**Validation Heuristics:**
- ✅ Lists colors with hex codes
- ✅ Has semantic color categories
- ✅ Shows accessibility contrast ratios
**Auto-Discovery:**
- Check: CSS variables or theme files (theme.js, theme.ts)
- Check: tailwind.config.js for color palette
- Scan: src/styles/ for color definitions
**MCP Ref Hints:**
- Research: "accessible color palette design"
- Research: "WCAG color contrast requirements"
<!-- QUESTION_END: 24 -->
<!-- DOCUMENT_END: docs/project/design_guidelines.md -->
---
<!-- DOCUMENT_START: docs/project/runbook.md -->
## docs/project/runbook.md
**File:** docs/project/runbook.md (operations guide)
**Target Sections:** Local Development Setup, Deployment, Troubleshooting
**Rules for this document:**
- Step-by-step setup instructions
- Environment variables documented
- Common issues and solutions
---
<!-- QUESTION_START: 25 -->
### Question 25: How do I set up the project locally?
**Expected Answer:** Prerequisites (Node.js version, Docker, etc.), installation steps (npm install, env setup), run commands (npm start, docker-compose up)
**Target Section:** ## Local Development Setup
**Validation Heuristics:**
- ✅ Lists prerequisites with versions
- ✅ Has numbered installation steps
- ✅ Has run commands for development
**Auto-Discovery:**
- Check: package.json → "engines" for version requirements (node, npm)
- Check: package.json → "scripts" for run commands (dev, start, build)
- Check: README.md for setup instructions
- Check: Dockerfile for runtime requirements
**MCP Ref Hints:**
- N/A (project-specific setup)
<!-- QUESTION_END: 25 -->
---
<!-- QUESTION_START: 26 -->
### Question 26: How is the application deployed?
**Expected Answer:** Deployment target (AWS, Vercel, Heroku, Docker), build commands, environment variables, deployment steps
**Target Section:** ## Deployment
**Validation Heuristics:**
- ✅ Mentions deployment platform
- ✅ Has build commands
- ✅ Lists required env vars
- ✅ Shows deployment steps or CI/CD pipeline
**Auto-Discovery:**
- Check: package.json → "scripts" → "build"
- Check: .env.example for required env vars
- Check: Dockerfile, vercel.json, .platform.app.yaml for deployment config
- Check: .github/workflows/ for CI/CD
**MCP Ref Hints:**
- Research: "[platform] deployment best practices"
- Research: "CI/CD pipeline setup for [platform]"
<!-- QUESTION_END: 26 -->
---
<!-- QUESTION_START: 27 -->
### Question 27: How do I troubleshoot common issues?
**Expected Answer:** Common errors with solutions, debugging techniques, log locations
**Target Section:** ## Troubleshooting
**Validation Heuristics:**
- ✅ Lists common errors and solutions
- ✅ Mentions debugging techniques
- ✅ Shows log locations or commands
**Auto-Discovery:**
- Check: package.json → "dependencies" for logging libraries (winston, pino, bunyan)
- Scan: README.md for troubleshooting section
- Check: .gitignore for log file patterns (*.log, logs/)
**MCP Ref Hints:**
- Research: "[framework] common issues troubleshooting"
- Research: "debugging best practices for [runtime]"
<!-- QUESTION_END: 27 -->
<!-- DOCUMENT_END: docs/project/runbook.md -->
---
**Overall Validation Rules:**
- ✅ All 7 documents exist (3 always required + 4 conditional)
- ✅ Each document has SCOPE tags
- ✅ Each document has Maintenance section
- ✅ Total questions answered: 27/27 for full-stack projects, 22/27 for backend-only, 24/27 for frontend-only
---
**Version:** 1.0.0
**Last Updated:** 2025-11-18

373
skills/ln-114-project-docs-creator/references/templates/api_spec_template.md Normal file
View File

@@ -0,0 +1,373 @@
# API Specification: {{PROJECT_NAME}}
**Document Version:** 1.0
**Date:** {{DATE}}
**Status:** {{STATUS}}
**OpenAPI Version:** 3.0.3
<!-- SCOPE: API endpoints (methods, paths, parameters, responses), authentication mechanisms (JWT, OAuth2, API keys), error codes (HTTP status + custom codes), rate limiting, API versioning ONLY. -->
<!-- DO NOT add here: Database schema → database_schema.md, Tech stack versions → tech_stack.md, Architecture patterns → architecture.md, Requirements → requirements.md, Deployment → runbook.md, Design system → design_guidelines.md -->
---
## 1. API Overview
### 1.1 Base URL
{{BASE_URL}}
<!-- Example: Development: http://localhost:3000/api/v1, Production: https://api.example.com/v1 -->
### 1.2 API Design Principles
{{API_DESIGN_PRINCIPLES}}
<!-- Example: RESTful design, Stateless communication, JSON request/response format, HATEOAS links for discoverability, Consistent error handling -->
### 1.3 API Versioning
{{API_VERSIONING}}
<!-- Example: URI versioning (/api/v1/, /api/v2/), Deprecation policy (6 months notice), Backward compatibility for minor updates -->
---
## 2. Authentication & Authorization
### 2.1 Authentication Methods
**Supported Methods:**
{{AUTH_METHODS}}
<!-- Example: JWT Bearer tokens (primary), OAuth2 (Google, GitHub), API Keys (for service-to-service) -->
**JWT Token Format:**
```json
{
"header": {
"alg": "HS256",
"typ": "JWT"
},
"payload": {
"sub": "user_id",
"role": "admin",
"exp": 1234567890
}
}
```
**Token Expiration:**
{{TOKEN_EXPIRATION}}
<!-- Example: Access token: 1 hour, Refresh token: 30 days -->
### 2.2 Authorization (RBAC)
**Roles:**
{{RBAC_ROLES}}
<!-- Example:
| Role | Permissions | Description |
|------|-------------|-------------|
| Admin | Full access | System administration |
| Editor | Read, Create, Update | Content management |
| Viewer | Read only | View-only access |
-->
---
## 3. API Endpoints
### 3.1 Authentication Endpoints
| Method | Endpoint | Description | Auth Required |
|--------|----------|-------------|---------------|
| POST | `/auth/register` | Register new user | No |
| POST | `/auth/login` | Login (email/password) | No |
| POST | `/auth/refresh` | Refresh access token | Yes (Refresh token) |
| POST | `/auth/logout` | Logout (invalidate tokens) | Yes |
| GET | `/auth/me` | Get current user info | Yes |
**Example: POST /auth/login**
Request:
```json
{
"email": "user@example.com",
"password": "secure_password"
}
```
Response (200 OK):
```json
{
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 3600,
"user": {
"id": "uuid",
"email": "user@example.com",
"role": "editor"
}
}
```
---
### 3.2 User Management Endpoints
| Method | Endpoint | Description | Auth Required | Roles |
|--------|----------|-------------|---------------|-------|
| GET | `/users` | List all users (paginated) | Yes | Admin |
| GET | `/users/:id` | Get user by ID | Yes | Admin, self |
| PUT | `/users/:id` | Update user | Yes | Admin, self |
| DELETE | `/users/:id` | Delete user | Yes | Admin |
| PATCH | `/users/:id/password` | Change password | Yes | Admin, self |
**Example: GET /users?page=1&limit=20**
Response (200 OK):
```json
{
"data": [
{
"id": "uuid",
"email": "user@example.com",
"role": "editor",
"createdAt": "2024-01-01T00:00:00Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 150,
"totalPages": 8
}
}
```
---
### 3.3 {{RESOURCE_1}} Endpoints
| Method | Endpoint | Description | Auth Required |
|--------|----------|-------------|---------------|
| GET | `/{{resource}}` | List {{resource}} | Yes |
| GET | `/{{resource}}/:id` | Get {{resource}} by ID | Yes |
| POST | `/{{resource}}` | Create {{resource}} | Yes |
| PUT | `/{{resource}}/:id` | Update {{resource}} | Yes |
| DELETE | `/{{resource}}/:id` | Delete {{resource}} | Yes |
<!-- Example: Products
| GET | `/products` | List products | Yes |
| GET | `/products/:id` | Get product by ID | Yes |
| POST | `/products` | Create product | Yes (Editor+) |
| PUT | `/products/:id` | Update product | Yes (Editor+) |
| DELETE | `/products/:id` | Delete product | Yes (Admin) |
-->
---
### 3.4 {{RESOURCE_2}} Endpoints
{{RESOURCE_2_ENDPOINTS}}
<!-- Repeat structure from 3.3 for additional resources: Orders, Categories, etc. -->
---
## 4. Request & Response Formats
### 4.1 Common Query Parameters
| Parameter | Type | Description | Example |
|-----------|------|-------------|---------|
| `page` | integer | Page number (1-based) | `?page=2` |
| `limit` | integer | Items per page (max 100) | `?limit=50` |
| `sort` | string | Sort field (+asc, -desc) | `?sort=-createdAt` |
| `filter` | string | Filter expression | `?filter=status:active` |
| `search` | string | Search query | `?search=keyword` |
### 4.2 Standard Response Structure
**Success Response:**
```json
{
"data": { /* resource data */ },
"meta": { /* metadata, pagination */ }
}
```
**Error Response:**
```json
{
"error": {
"code": "ERROR_CODE",
"message": "Human-readable error message",
"details": [ /* validation errors, if applicable */ ]
}
}
```
---
## 5. Error Codes
### 5.1 HTTP Status Codes
| Status | Meaning | When Used |
|--------|---------|-----------|
| 200 | OK | Successful GET, PUT, PATCH |
| 201 | Created | Successful POST |
| 204 | No Content | Successful DELETE |
| 400 | Bad Request | Invalid request format, validation errors |
| 401 | Unauthorized | Missing or invalid authentication token |
| 403 | Forbidden | Authenticated but insufficient permissions |
| 404 | Not Found | Resource not found |
| 409 | Conflict | Duplicate resource (email already exists) |
| 422 | Unprocessable Entity | Validation errors |
| 429 | Too Many Requests | Rate limit exceeded |
| 500 | Internal Server Error | Unexpected server error |
### 5.2 Custom Error Codes
| Code | HTTP Status | Description | Example |
|------|-------------|-------------|---------|
| `AUTH_INVALID_CREDENTIALS` | 401 | Invalid email/password | Login failed |
| `AUTH_TOKEN_EXPIRED` | 401 | JWT token expired | Token needs refresh |
| `AUTH_INSUFFICIENT_PERMISSIONS` | 403 | User lacks required role | Admin-only action |
| `VALIDATION_FAILED` | 422 | Input validation failed | Missing required field |
| `RESOURCE_NOT_FOUND` | 404 | Requested resource not found | User ID not found |
| `RESOURCE_CONFLICT` | 409 | Resource already exists | Email already registered |
| `RATE_LIMIT_EXCEEDED` | 429 | Too many requests | 100 req/min limit hit |
**Example Error Response:**
```json
{
"error": {
"code": "VALIDATION_FAILED",
"message": "Validation failed for request body",
"details": [
{
"field": "email",
"message": "Invalid email format"
},
{
"field": "password",
"message": "Password must be at least 8 characters"
}
]
}
}
```
---
## 6. Rate Limiting
**Limits:**
{{RATE_LIMITS}}
<!-- Example:
| Endpoint Type | Limit | Window |
|--------------|-------|--------|
| Authentication | 5 requests | 15 minutes |
| Read (GET) | 100 requests | 1 minute |
| Write (POST/PUT/DELETE) | 30 requests | 1 minute |
-->
**Rate Limit Headers:**
```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 75
X-RateLimit-Reset: 1640000000
```
---
## 7. Pagination
**Request:**
```
GET /users?page=2&limit=20
```
**Response:**
```json
{
"data": [ /* 20 users */ ],
"pagination": {
"page": 2,
"limit": 20,
"total": 150,
"totalPages": 8,
"hasNext": true,
"hasPrev": true
},
"links": {
"self": "/users?page=2&limit=20",
"first": "/users?page=1&limit=20",
"prev": "/users?page=1&limit=20",
"next": "/users?page=3&limit=20",
"last": "/users?page=8&limit=20"
}
}
```
---
## 8. OpenAPI Specification
**OpenAPI Documentation:**
{{OPENAPI_LINK}}
<!-- Example: Swagger UI available at `/api-docs`, OpenAPI JSON at `/api-docs.json` -->
**Example OpenAPI Snippet (users endpoint):**
```yaml
paths:
/users:
get:
summary: List all users
tags: [Users]
security:
- bearerAuth: []
parameters:
- name: page
in: query
schema:
type: integer
default: 1
- name: limit
in: query
schema:
type: integer
default: 20
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/User'
pagination:
$ref: '#/components/schemas/Pagination'
```
---
## 9. Maintenance
**Last Updated:** {{DATE}}
**Update Triggers:**
- New API endpoints added
- Authentication/authorization changes
- Error code modifications
- Rate limiting adjustments
- API versioning (major/minor releases)
**Verification:**
- [ ] All endpoints documented with methods/paths/params/responses
- [ ] Authentication requirements specified for each endpoint
- [ ] Error codes match implementation
- [ ] OpenAPI specification up to date
- [ ] Rate limits tested and validated
---
**Version:** 1.0.0
**Template Last Updated:** 2025-11-16

271
skills/ln-114-project-docs-creator/references/templates/architecture_template.md Normal file
View File

@@ -0,0 +1,271 @@
# Software Architecture Document: {{PROJECT_NAME}}
**Document Version:** 1.0
**Date:** {{DATE}}
**Status:** {{STATUS}}
**Architecture Framework:** arc42 (simplified)
**Standard Compliance:** ISO/IEC/IEEE 42010:2022
<!-- SCOPE: System architecture (arc42 structure), C4 diagrams (Context, Container, Component), runtime scenarios (sequence diagrams), crosscutting concepts (security, error handling, configuration), ADR references ONLY. -->
<!-- DO NOT add here: Deployment procedures → runbook.md, Testing strategy → tests/README.md, Monitoring/Logging operations → runbook.md, Tech stack versions → tech_stack.md, API specs → api_spec.md, Database schema → database_schema.md, Design system → design_guidelines.md, Requirements → requirements.md -->
---
## 1. Introduction and Goals
### 1.1 Requirements Overview
{{REQUIREMENTS_OVERVIEW}}
<!-- Example: Brief summary of key functional requirements from Requirements Document and quality goals from Section 1.2 -->
### 1.2 Quality Goals
{{QUALITY_GOALS}}
<!-- Example: 1. Performance: <200ms (p95), 2. Security: GDPR compliance + AES-256, 3. Scalability: 1K→500K users, 4. Reliability: 99.9% uptime, 5. Maintainability: <5% technical debt -->
### 1.3 Stakeholders
{{STAKEHOLDERS_SUMMARY}}
<!-- Example: Product Owner (business direction), Development Team (implementation), DevOps (infrastructure), End Users (consumers), QA (quality assurance) -->
---
## 2. Constraints
### 2.1 Technical Constraints
{{TECHNICAL_CONSTRAINTS}}
<!-- Example: Languages: TypeScript/Node.js (team expertise), Database: PostgreSQL 12 (locked until Q2 2025), Cloud: AWS (company standard), Browser: Chrome/Firefox/Safari last 2 versions -->
### 2.2 Organizational Constraints
{{ORGANIZATIONAL_CONSTRAINTS}}
<!-- Example: Team Size: 11 people (no new hires this quarter), Compliance: GDPR mandatory (EU market), Process: Agile/Scrum 2-week sprints -->
### 2.3 Conventions
{{CONVENTIONS}}
<!-- Example: Code: ESLint+Prettier (CI enforced), Git: GitHub Flow, API: RESTful+JSON+semantic versioning, Testing: Risk-Based (2-5 E2E, 3-8 Integration, 5-15 Unit, Priority ≥15) -->
---
## 3. Context and Scope
### 3.1 Business Context
{{BUSINESS_CONTEXT}}
<!-- Example: System provides e-commerce platform connecting Customers (browsing/purchasing) and Admins (managing content) with external services: Payment Gateway (Stripe), Email (SendGrid), Auth (Okta) -->
**Business Context Diagram:**
```mermaid
{{BUSINESS_CONTEXT_DIAGRAM}}
```
**External Interfaces:**
{{EXTERNAL_INTERFACES}}
<!-- Example table: Stripe API | External | HTTPS REST | Payment processing | SendGrid API | External | HTTPS REST | Email notifications -->
### 3.2 Technical Context
{{TECHNICAL_CONTEXT}}
<!-- Example: Web Browser (HTTPS) → API Gateway → Application Server (Node.js) → PostgreSQL Database + Redis Cache + RabbitMQ Queue -->
**Technical Context Diagram:**
```mermaid
{{TECHNICAL_CONTEXT_DIAGRAM}}
```
---
## 4. Solution Strategy
### 4.1 Technology Decisions
{{TECHNOLOGY_DECISIONS}}
<!-- Example table: Frontend | React 18+Next.js 14 | SSR for SEO, team expertise | ADR-001 | Backend | Node.js+Express | JavaScript fullstack, async I/O | ADR-002 | Database | PostgreSQL 15 | ACID, JSON support, mature | ADR-003 -->
### 4.2 Top-Level Decomposition
{{TOP_LEVEL_DECOMPOSITION}}
<!-- Example: Layered Architecture (4 layers): Presentation (Next.js+React) → API (Express REST) → Business Logic (Service classes) → Data (Repositories+PostgreSQL+Redis). Rationale: Separation of concerns, testability, team familiarity -->
### 4.3 Approach to Quality Goals
{{QUALITY_APPROACH}}
<!-- Example table: Performance <200ms | Redis caching, DB indexing, CDN, async I/O | Security GDPR | Encryption at rest/transit, OAuth2, RBAC, audit logging | Scalability 500K | Horizontal scaling (K8s), stateless API, DB read replicas -->
---
## 5. Building Block View
### 5.1 Level 1: System Context (C4 Model)
{{SYSTEM_CONTEXT}}
<!-- Example: Highest level view - System as black box with external actors (Customers, Admins) and external systems (Stripe, SendGrid, Okta) -->
**System Context Diagram:**
```mermaid
{{SYSTEM_CONTEXT_DIAGRAM}}
```
### 5.2 Level 2: Container Diagram (C4 Model)
{{CONTAINER_DIAGRAM}}
<!-- Example: Deployable units - Web App (Next.js), API (Node.js+Express), Background Workers (Node.js), Database (PostgreSQL), Cache (Redis), Queue (RabbitMQ) -->
**Container Diagram:**
```mermaid
{{CONTAINER_DIAGRAM_MERMAID}}
```
### 5.3 Level 3: Component Diagram (C4 Model)
{{COMPONENT_DIAGRAM}}
<!-- Example: API breakdown - Controllers (HTTP endpoints) → Services (business logic) → Repositories (data access) + Middleware (auth, logging, errors) -->
**Components within API Container:**
```mermaid
{{COMPONENT_DIAGRAM_MERMAID}}
```
**Key Components:**
{{KEY_COMPONENTS}}
<!-- Example table: AuthController | Handle login/register endpoints | AuthService, JWTService | ProductService | Product catalog business logic | ProductRepository, CacheService | OrderService | Order processing workflow | OrderRepository, PaymentClient, EmailClient -->
**Infrastructure Layer Components:**
{{INFRASTRUCTURE_COMPONENTS}}
<!-- Example table:
Component | Responsibility | Dependencies
DataAccess/ | EF Core DbContext, Repositories, Migrations | PostgreSQL, Entity Framework
ExternalServices/ | Third-party integrations (Excel, PDF, Email) | ClosedXML, QuestPDF, MailKit
Localization/ | Resource files, culture management | Microsoft.Extensions.Localization
-->
---
## 6. Runtime View
### 6.1 Scenario 1: User Registration
{{SCENARIO_USER_REGISTRATION}}
<!-- Example: User fills form → Web App POST /api/v1/auth/register → API validates + hashes password → DB creates user → Email Service sends verification → User receives success message -->
**Sequence Diagram:**
```mermaid
{{SCENARIO_1_SEQUENCE_DIAGRAM}}
```
### 6.2 Scenario 2: Product Purchase Flow
{{SCENARIO_PURCHASE_FLOW}}
<!-- Example: User clicks Purchase → API creates order → Payment Client calls Stripe → Queue publishes order_created → Background Worker sends confirmation email + updates DB status -->
**Sequence Diagram:**
```mermaid
{{SCENARIO_2_SEQUENCE_DIAGRAM}}
```
### 6.3 [Additional Key Scenarios]
{{ADDITIONAL_SCENARIOS}}
<!-- Example: Add 2-3 more critical scenarios with sequence diagrams (e.g., Password Reset, Search Products, Admin Content Update) -->
---
## 7. Crosscutting Concepts
### 7.1 Security Concept
{{SECURITY_CONCEPT}}
<!-- Example: Auth: JWT (1h expiration) + refresh tokens (30d), Authorization: RBAC (5 roles), Encryption: TLS 1.3 (transit) + AES-256 (at rest for PII), API: Rate limiting (100 req/min), Secrets: AWS Secrets Manager (prod), Audit: All write operations logged -->
### 7.2 Error Handling Concept
{{ERROR_HANDLING_CONCEPT}}
<!-- Example: Custom domain exceptions (PaymentFailedError, UserNotFoundError), Global Express middleware catches all, JSON format {error: {code, message, details}}, Logging with trace_id + stack (Datadog), Sanitized user-facing messages, Retry: Exponential backoff for transient failures -->
### 7.3 Configuration Management Concept
{{CONFIG_MANAGEMENT_CONCEPT}}
<!-- Example: Env vars: .env (dev) + AWS Secrets Manager (prod), Library: dotenv + Joi validation, Environments: Dev (local) + Staging (AWS) + Production (AWS), Secrets: Never in Git, rotated quarterly, Feature Flags: LaunchDarkly or custom Redis-based -->
### 7.4 Data Access Pattern
{{DATA_ACCESS_PATTERN}}
<!-- Example: Repository Pattern (Generic + Specific repositories), Unit of Work via DbContext.SaveChanges(), EF Core code-first migrations, Connection pooling (default 100), Lazy loading disabled (explicit Include()), Query optimization (AsNoTracking() for reads), Transaction management (explicit for multi-repo operations) -->
---
## 8. Architecture Decisions (ADRs)
{{ADR_LIST}}
<!-- Example: List all ADRs with links - [ADR-001](../adrs/adr-001-frontend-framework.md) Use React+Next.js | Accepted | 2024-10-15 -->
**Critical ADRs Summary:**
{{CRITICAL_ADRS_SUMMARY}}
<!-- Example: Brief summary of top 3-5 most impactful decisions (e.g., ADR-001 React+Next.js for SEO requirements, ADR-003 PostgreSQL for ACID compliance, ADR-007 Kubernetes for horizontal scalability) -->
---
## 9. Quality Requirements
### 9.1 Quality Tree
{{QUALITY_TREE}}
<!-- Example: ISO 25010 hierarchy - Performance (Response time <200ms p95, Throughput >10K req/sec), Security (Authentication: OAuth2+JWT, Authorization: RBAC, Encryption: TLS 1.3+AES-256), Scalability (Horizontal: 1K→500K users), Reliability (Uptime: 99.9%, Failover: <60s), Maintainability (Code coverage >80%, Tech debt <5%) -->
### 9.2 Quality Scenarios
{{QUALITY_SCENARIOS}}
<!-- Example table: QS-1 | Performance | User searches "laptop", system returns results | <200ms (p95) | MUST | QS-2 | Scalability | Black Friday spike 1K→50K concurrent users | No degradation | MUST | QS-3 | Security | Attacker SQL injection on login | Attack blocked + logged | MUST -->
---
## 10. Risks and Technical Debt
### 10.1 Known Technical Risks
{{TECHNICAL_RISKS}}
<!-- Example: 1. PostgreSQL 12 EOL approaching (security risk), 2. No database sharding (scalability limit at 5TB), 3. Single region deployment (DR risk), 4. Third-party API dependency (Stripe downtime impact) -->
### 10.2 Technical Debt
{{TECHNICAL_DEBT}}
<!-- Example table: PostgreSQL 12 EOL | Security risk | Upgrade to PG 15 | Q2 2025 | No database sharding | Scalability limit 5TB | Implement sharding | Year 2 | Monolithic deployment | Slow rollouts | Migrate to microservices | Q3 2025 -->
### 10.3 Mitigation Strategies
{{MITIGATION_STRATEGIES}}
<!-- Example: 1. PostgreSQL upgrade: Plan migration window Q2 2025, test on staging first, 2. Sharding: Design partition strategy (by user_id hash), 3. Microservices: Incremental extraction (start with payment service), 4. Stripe dependency: Implement circuit breaker + fallback queue -->
---
## 11. Glossary
| Term | Definition |
|------|------------|
| {{TERM_1}} | {{DEFINITION_1}} |
| Container | Deployable/runnable unit (C4 Model), NOT Docker container |
| Component | Grouping of related functionality within a container |
| SSR | Server-Side Rendering |
| RBAC | Role-Based Access Control |
| JWT | JSON Web Token |
---
## 12. References
1. arc42 Architecture Template v8.2 - https://arc42.org/
2. C4 Model for Visualizing Software Architecture - https://c4model.com/
3. ISO/IEC/IEEE 42010:2022 - Architecture description
4. Michael Nygard's ADR Format - https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
5. {{PROJECT_NAME}} Requirements Document
6. {{PROJECT_NAME}} ADRs Directory
---
## Maintenance
**Last Updated:** {{DATE}}
**Update Triggers:**
- New architectural decisions (create new ADR, update Section 8)
- New microservices or containers added (update C4 Container diagram)
- New components in existing services (update C4 Component diagram)
- New external systems or integrations (update Context diagram)
- Major refactoring affecting system structure
- Changes to quality requirements or scenarios
**Verification:**
- [ ] All C4 diagrams (Context, Container, Component) are consistent
- [ ] All ADRs referenced in Section 8 exist in adrs/ directory
- [ ] Runtime view scenarios cover main use cases
- [ ] All external systems documented in Technical Context
- [ ] All placeholders replaced with actual content
---
## Revision History
| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.0 | {{DATE}} | {{AUTHOR}} | Initial version |
---
**Version:** 4.0.0 (Added Infrastructure Layer guidance: Section 5.3 Infrastructure Components + Section 7.4 Data Access Pattern)
**Template Last Updated:** 2025-11-18

293
skills/ln-114-project-docs-creator/references/templates/database_schema_template.md Normal file
View File

@@ -0,0 +1,293 @@
# Database Schema: {{PROJECT_NAME}}
**Document Version:** 1.0
**Date:** {{DATE}}
**Status:** {{STATUS}}
<!-- SCOPE: Database schema (ER diagrams, table definitions, data dictionary, indexes, constraints, migrations, normalization) ONLY. -->
<!-- DO NOT add here: API endpoints → api_spec.md, Tech stack versions → tech_stack.md, Architecture patterns → architecture.md, Requirements → requirements.md, Deployment → runbook.md -->
---
## 1. Introduction
### 1.1 Purpose
This document specifies the database schema, entity relationships, and data dictionary for {{PROJECT_NAME}}.
### 1.2 Database System
{{DATABASE_SYSTEM}}
<!-- Example: PostgreSQL 16.x, MySQL 8.x, MongoDB 7.x -->
### 1.3 Normalization Level
{{NORMALIZATION_LEVEL}}
<!-- Example: Third Normal Form (3NF) with selective denormalization for performance -->
---
## 2. Entity Relationship Diagram
### 2.1 High-Level ER Diagram
```mermaid
erDiagram
{{ER_DIAGRAM_ENTITIES_RELATIONSHIPS}}
```
<!-- Example:
```mermaid
erDiagram
USERS ||--o{ ORDERS : places
USERS ||--o{ REVIEWS : writes
ORDERS ||--|{ ORDER_ITEMS : contains
PRODUCTS ||--o{ ORDER_ITEMS : "ordered in"
PRODUCTS ||--o{ REVIEWS : "reviewed in"
CATEGORIES ||--o{ PRODUCTS : contains
USERS {
uuid id PK
string email UK
string password_hash
string role
timestamp created_at
}
PRODUCTS {
uuid id PK
uuid category_id FK
string name
text description
decimal price
int stock_quantity
}
ORDERS {
uuid id PK
uuid user_id FK
decimal total_amount
string status
timestamp created_at
}
```
-->
---
## 3. Data Dictionary
### 3.1 {{TABLE_1}} Table
**Table Name:** `{{table_1}}`
**Description:** {{TABLE_1_DESCRIPTION}}
<!-- Example: users - Stores user account information including authentication credentials and profile data -->
| Column | Type | Null | Default | Constraints | Description |
|--------|------|------|---------|-------------|-------------|
| `id` | UUID | NO | gen_random_uuid() | PRIMARY KEY | Unique user identifier |
| `email` | VARCHAR(255) | NO | - | UNIQUE, CHECK (email ~* '^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}$') | User email address |
| `password_hash` | VARCHAR(255) | NO | - | - | bcrypt hashed password |
| `first_name` | VARCHAR(100) | YES | NULL | - | User first name |
| `last_name` | VARCHAR(100) | YES | NULL | - | User last name |
| `role` | VARCHAR(20) | NO | 'viewer' | CHECK (role IN ('admin', 'editor', 'viewer')) | User role for RBAC |
| `is_active` | BOOLEAN | NO | TRUE | - | Account status |
| `created_at` | TIMESTAMP | NO | CURRENT_TIMESTAMP | - | Account creation timestamp |
| `updated_at` | TIMESTAMP | NO | CURRENT_TIMESTAMP | ON UPDATE CURRENT_TIMESTAMP | Last update timestamp |
**Indexes:**
```sql
CREATE UNIQUE INDEX idx_users_email ON users(email);
CREATE INDEX idx_users_role ON users(role);
CREATE INDEX idx_users_created_at ON users(created_at);
```
**Relationships:**
- `users.id` → `orders.user_id` (One-to-Many)
- `users.id` → `reviews.user_id` (One-to-Many)
---
### 3.2 {{TABLE_2}} Table
**Table Name:** `{{table_2}}`
**Description:** {{TABLE_2_DESCRIPTION}}
<!-- Example: products - Product catalog with pricing, inventory, and categorization -->
| Column | Type | Null | Default | Constraints | Description |
|--------|------|------|---------|-------------|-------------|
| `id` | UUID | NO | gen_random_uuid() | PRIMARY KEY | Product identifier |
| `category_id` | UUID | NO | - | FOREIGN KEY REFERENCES categories(id) ON DELETE RESTRICT | Product category |
| `name` | VARCHAR(200) | NO | - | - | Product name |
| `slug` | VARCHAR(220) | NO | - | UNIQUE | URL-friendly name |
| `description` | TEXT | YES | NULL | - | Product description |
| `price` | DECIMAL(10,2) | NO | - | CHECK (price >= 0) | Product price (USD) |
| `stock_quantity` | INTEGER | NO | 0 | CHECK (stock_quantity >= 0) | Available inventory |
| `is_published` | BOOLEAN | NO | FALSE | - | Publish status |
| `created_at` | TIMESTAMP | NO | CURRENT_TIMESTAMP | - | Creation timestamp |
| `updated_at` | TIMESTAMP | NO | CURRENT_TIMESTAMP | ON UPDATE CURRENT_TIMESTAMP | Last update timestamp |
**Indexes:**
```sql
CREATE UNIQUE INDEX idx_products_slug ON products(slug);
CREATE INDEX idx_products_category_id ON products(category_id);
CREATE INDEX idx_products_is_published ON products(is_published);
CREATE INDEX idx_products_price ON products(price);
```
**Relationships:**
- `categories.id` → `products.category_id` (One-to-Many)
- `products.id` → `order_items.product_id` (One-to-Many)
- `products.id` → `reviews.product_id` (One-to-Many)
---
### 3.3 {{TABLE_3}} Table
{{TABLE_3_DEFINITION}}
<!-- Repeat structure from 3.1/3.2 for additional tables: orders, order_items, categories, reviews, etc. -->
---
## 4. Database Constraints
### 4.1 Foreign Key Constraints
| FK Name | Child Table | Child Column | Parent Table | Parent Column | On Delete | On Update |
|---------|-------------|--------------|--------------|---------------|-----------|-----------|
| `fk_orders_user` | orders | user_id | users | id | CASCADE | CASCADE |
| `fk_products_category` | products | category_id | categories | id | RESTRICT | CASCADE |
| `fk_order_items_order` | order_items | order_id | orders | id | CASCADE | CASCADE |
| `fk_order_items_product` | order_items | product_id | products | id | RESTRICT | CASCADE |
<!-- Example explanations:
- CASCADE: If parent deleted, delete child rows
- RESTRICT: Prevent parent deletion if children exist
- SET NULL: Set child FK to NULL if parent deleted
-->
### 4.2 Check Constraints
| Constraint Name | Table | Expression | Description |
|-----------------|-------|------------|-------------|
| `chk_users_role` | users | `role IN ('admin', 'editor', 'viewer')` | Valid role values |
| `chk_products_price` | products | `price >= 0` | Non-negative price |
| `chk_products_stock` | products | `stock_quantity >= 0` | Non-negative stock |
| `chk_orders_status` | orders | `status IN ('pending', 'paid', 'shipped', 'delivered', 'canceled')` | Valid order statuses |
---
## 5. Indexes Strategy
### 5.1 Primary Indexes
{{PRIMARY_INDEXES}}
<!-- Example: All tables use UUID primary keys for distributed scalability and security (no sequential IDs) -->
### 5.2 Secondary Indexes
{{SECONDARY_INDEXES}}
<!-- Example:
- Email lookup: idx_users_email (UNIQUE) - fast authentication
- Category filtering: idx_products_category_id - product catalog queries
- Order history: idx_orders_user_id - user dashboard
- Price range queries: idx_products_price - product search/filter
-->
### 5.3 Composite Indexes
{{COMPOSITE_INDEXES}}
<!-- Example:
```sql
CREATE INDEX idx_products_category_published ON products(category_id, is_published);
CREATE INDEX idx_orders_user_created ON orders(user_id, created_at DESC);
```
Purpose: Optimize common query patterns (published products by category, recent orders by user)
-->
---
## 6. Database Migrations
### 6.1 Migration Tool
{{MIGRATION_TOOL}}
<!-- Example: Prisma Migrate, Flyway, Liquibase, Alembic (Python), TypeORM migrations -->
### 6.2 Migration Strategy
{{MIGRATION_STRATEGY}}
<!-- Example:
- Versioned migrations (001_initial_schema.sql, 002_add_reviews.sql)
- Up/Down scripts for rollback capability
- Automated migration on deployment (CI/CD)
- Manual review for production migrations (peer review required)
-->
### 6.3 Migration Examples
**Migration 001: Initial Schema**
```sql
-- Up Migration
CREATE TABLE users (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
email VARCHAR(255) UNIQUE NOT NULL,
password_hash VARCHAR(255) NOT NULL,
role VARCHAR(20) NOT NULL DEFAULT 'viewer',
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);
-- Down Migration
DROP TABLE IF EXISTS users;
```
**Migration 002: Add Soft Delete**
```sql
-- Up Migration
ALTER TABLE users ADD COLUMN deleted_at TIMESTAMP NULL;
CREATE INDEX idx_users_deleted_at ON users(deleted_at);
-- Down Migration
ALTER TABLE users DROP COLUMN deleted_at;
```
---
## 7. Data Types & Standards
### 7.1 Common Data Types
| Logical Type | PostgreSQL Type | MySQL Type | Description |
|--------------|----------------|------------|-------------|
| UUID | UUID | CHAR(36) | Unique identifiers |
| Money | DECIMAL(10,2) | DECIMAL(10,2) | Currency values (2 decimal places) |
| Timestamp | TIMESTAMP | DATETIME | Date and time (UTC) |
| Boolean | BOOLEAN | TINYINT(1) | True/false values |
| JSON | JSONB | JSON | Semi-structured data |
### 7.2 Naming Conventions
{{NAMING_CONVENTIONS}}
<!-- Example:
- Tables: snake_case plural (users, order_items)
- Columns: snake_case (first_name, created_at)
- Indexes: idx_table_column (idx_users_email)
- Foreign Keys: fk_child_parent (fk_orders_user)
- Primary Keys: Always named 'id'
-->
---
## 8. Maintenance
**Last Updated:** {{DATE}}
**Update Triggers:**
- New tables added
- Schema changes (columns, indexes, constraints)
- Migration scripts created
- Denormalization for performance
- Relationship changes
**Verification:**
- [ ] All tables documented with columns/types/constraints
- [ ] ER diagram matches actual schema
- [ ] Indexes match query patterns
- [ ] Foreign keys enforce referential integrity
- [ ] Migrations tested (up + down)
---
**Version:** 1.0.0
**Template Last Updated:** 2025-11-16

351
skills/ln-114-project-docs-creator/references/templates/design_guidelines_template.md Normal file
View File

@@ -0,0 +1,351 @@
# Design Guidelines: {{PROJECT_NAME}}
**Document Version:** 1.0
**Date:** {{DATE}}
**Status:** {{STATUS}}
<!-- SCOPE: UI/UX design system (typography, colors, spacing, grid), component library (buttons, forms, cards, navigation, modals), layout patterns (page templates), accessibility guidelines (WCAG AA, keyboard, ARIA), responsive behavior (breakpoints, adaptations), branding (logo, imagery, icons) ONLY. -->
<!-- DO NOT add here: Technical implementation → tech_stack.md, React/Vue code examples → Task descriptions, API contracts → api_spec.md, State management → architecture.md, Performance optimization → runbook.md -->
---
## 1. Design Approach
### 1.1 Design Philosophy
{{DESIGN_PHILOSOPHY}}
<!-- Example: Reference-Based Approach inspired by Airbnb Design System - professional, user-friendly, consistency across platform. Focuses on clarity, simplicity, and accessibility. -->
### 1.2 Design Inspiration
{{DESIGN_INSPIRATION}}
<!-- Example: Primary reference: example.com design system. Secondary influences: Material Design (components), Tailwind CSS (utility-first approach), Carbon Design System (enterprise patterns) -->
---
## 2. Core Design Elements
### 2.1 Typography
**Font Families:**
{{FONT_FAMILIES}}
<!-- Example:
- Primary (Body): Inter (400, 500, 600) - high legibility for long-form text
- Headings: Poppins (600, 700) - distinct hierarchy, professional
- Monospace: JetBrains Mono (400) - code snippets, technical content
-->
**Type Scale:**
{{TYPE_SCALE}}
<!-- Example (Tailwind CSS classes):
| Element | Class | Size | Line Height | Usage |
|---------|-------|------|-------------|-------|
| Hero | text-5xl | 48px | 1.2 | Landing page hero headlines |
| H1 | text-4xl | 36px | 1.25 | Page titles |
| H2 | text-2xl | 24px | 1.33 | Section headers |
| H3 | text-xl | 20px | 1.4 | Sub-section headers |
| Body | text-base | 16px | 1.5 | Paragraphs, content |
| Small | text-sm | 14px | 1.43 | Captions, labels |
| Tiny | text-xs | 12px | 1.33 | Metadata, timestamps |
-->
**Line Height:**
{{LINE_HEIGHT}}
<!-- Example: Headings: 1.2-1.33 (tight), Body: 1.5 (comfortable reading), UI elements: 1.25 (compact) -->
---
### 2.2 Color System
**Primary Colors:**
{{PRIMARY_COLORS}}
<!-- Example:
- Primary: #FF6B35 (Vibrant orange - CTAs, interactive elements)
- Secondary: #004E89 (Deep blue - headings, trust/authority)
- Accent: #1A936F (Teal green - highlights, success states)
-->
**Semantic Colors:**
{{SEMANTIC_COLORS}}
<!-- Example:
| Purpose | Color | Hex | Usage |
|---------|-------|-----|-------|
| Success | Green | #10B981 | Form success, confirmations |
| Warning | Amber | #F59E0B | Cautions, important notices |
| Error | Red | #EF4444 | Form errors, destructive actions |
| Info | Blue | #3B82F6 | Informational messages, tips |
-->
**Neutral Colors:**
{{NEUTRAL_COLORS}}
<!-- Example:
| Shade | Hex | Usage |
|-------|-----|-------|
| Dark Text | #1F2937 | Primary text, headings |
| Medium Gray | #6B7280 | Secondary text, labels |
| Light Gray | #F3F4F6 | Backgrounds, cards |
| Border | #E5E7EB | Dividers, input borders |
| White | #FFFFFF | Backgrounds, contrast |
-->
**Color Accessibility:**
{{COLOR_ACCESSIBILITY}}
<!-- Example: All color combinations meet WCAG 2.1 AA contrast ratio (4.5:1 for text, 3:1 for UI components). Primary on White: 4.8:1, Dark Text on Light Gray: 12.6:1 -->
---
### 2.3 Layout System
**Spacing Primitives:**
{{SPACING_SYSTEM}}
<!-- Example: Tailwind spacing units: 2 (0.5rem/8px), 4 (1rem/16px), 6 (1.5rem/24px), 8 (2rem/32px), 12 (3rem/48px), 16 (4rem/64px), 20 (5rem/80px), 24 (6rem/96px) -->
**Container Strategy:**
{{CONTAINER_STRATEGY}}
<!-- Example:
| Container Type | Max Width | Padding | Usage |
|----------------|-----------|---------|-------|
| Page | max-w-7xl (1280px) | px-6 | Main page wrapper |
| Content | max-w-6xl (1152px) | px-4 | Article content |
| Narrow | max-w-4xl (896px) | px-4 | Forms, focused content |
| Wide | max-w-full | px-8 | Dashboards, data tables |
-->
**Grid System:**
{{GRID_SYSTEM}}
<!-- Example: 12-column grid, gap-6 (24px), responsive breakpoints (sm/md/lg/xl/2xl). Example: `grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6` -->
---
### 2.4 Component Library
#### 2.4.1 Navigation
{{NAVIGATION_COMPONENTS}}
<!-- Example:
- **Header**: Fixed top, h-16 (64px), bg-white shadow-sm, z-50
- **Logo**: Left-aligned, h-8 (32px)
- **Main Menu**: Center (desktop), hamburger (mobile), active state: border-b-2 border-primary
- **User Menu**: Right-aligned, dropdown on click, avatar icon
-->
#### 2.4.2 Buttons
{{BUTTON_COMPONENTS}}
<!-- Example:
| Variant | Classes | Usage |
|---------|---------|-------|
| Primary | bg-primary text-white hover:bg-primary-dark px-6 py-3 rounded-lg | Primary CTAs, submit actions |
| Secondary | border-2 border-primary text-primary hover:bg-primary-light px-6 py-3 rounded-lg | Secondary actions |
| Text | text-primary hover:underline | Tertiary actions, links |
| Icon | p-2 rounded-full hover:bg-gray-100 | Icon-only buttons, close buttons |
Size variants: Small (px-4 py-2 text-sm), Medium (px-6 py-3 text-base), Large (px-8 py-4 text-lg)
-->
#### 2.4.3 Forms
{{FORM_COMPONENTS}}
<!-- Example:
- **Input Fields**: border border-gray-300 rounded-lg px-4 py-3 focus:ring-2 focus:ring-primary focus:border-primary
- **Labels**: text-sm font-medium text-gray-700 mb-2
- **Error Messages**: text-red-500 text-sm mt-1
- **Help Text**: text-gray-500 text-sm mt-1
- **Checkboxes/Radio**: Accent color matches primary, 44px min tap target
-->
#### 2.4.4 Cards
{{CARD_COMPONENTS}}
<!-- Example:
- **Default**: bg-white shadow-md rounded-lg border border-gray-200 p-6
- **Hover State**: hover:shadow-lg transition-shadow duration-200
- **Interactive**: cursor-pointer hover:border-primary
- **Image Card**: Image top (aspect-16/9), content below, rounded-t-lg for image
-->
#### 2.4.5 Modals & Dialogs
{{MODAL_COMPONENTS}}
<!-- Example:
- **Backdrop**: fixed inset-0 bg-black/50 z-40 backdrop-blur-sm
- **Modal**: fixed inset-0 flex items-center justify-center z-50
- **Content**: bg-white rounded-lg shadow-xl max-w-lg w-full p-6 m-4
- **Close Button**: Absolute top-right, p-2, X icon
- **Actions**: Right-aligned button group, primary + secondary
-->
#### 2.4.6 Tables
{{TABLE_COMPONENTS}}
<!-- Example:
- **Header**: bg-gray-50 text-left font-semibold text-gray-700 px-4 py-3
- **Rows**: border-b border-gray-200 hover:bg-gray-50
- **Cells**: px-4 py-3 text-gray-900
- **Responsive**: Horizontal scroll on mobile, sticky header optional
-->
---
### 2.5 Responsive Behavior
**Breakpoints:**
{{BREAKPOINTS}}
<!-- Example (Tailwind defaults):
| Breakpoint | Min Width | Device | Layout |
|------------|-----------|--------|--------|
| sm | 640px | Large phones | Single column, stacked nav |
| md | 768px | Tablets | 2-column grids, horizontal nav |
| lg | 1024px | Laptops | 3-column grids, full navigation |
| xl | 1280px | Desktops | 4-column grids, max-width containers |
| 2xl | 1536px | Large displays | Wide layouts, extra whitespace |
-->
**Layout Adaptations:**
{{RESPONSIVE_LAYOUTS}}
<!-- Example:
- **Desktop (>1024px)**: 3-column grid for products, sidebar navigation, header with full menu
- **Tablet (768-1024px)**: 2-column grid, hamburger menu, condensed header
- **Mobile (<768px)**: 1-column stack, bottom navigation, collapsible sections
- **Touch Targets**: Min 44x44px for all interactive elements on mobile
-->
---
## 3. Accessibility Guidelines
### 3.1 WCAG Compliance
{{WCAG_LEVEL}}
<!-- Example: WCAG 2.1 Level AA compliance (minimum). Contrast ratios: 4.5:1 for text, 3:1 for UI components. -->
### 3.2 Keyboard Navigation
{{KEYBOARD_NAVIGATION}}
<!-- Example:
- All interactive elements focusable via Tab key
- Visible focus ring: ring-2 ring-primary ring-offset-2
- Logical tab order (top-to-bottom, left-to-right)
- Skip to main content link (hidden, appears on Tab)
- Modal focus trap (Tab cycles within modal)
-->
### 3.3 Screen Reader Support
{{SCREEN_READER}}
<!-- Example:
- ARIA labels for icon buttons: aria-label="Close dialog"
- Semantic HTML: <nav>, <main>, <article>, <aside>
- Table headers with scope attribute
- Form labels associated with inputs (for/id)
- Alt text for all images (descriptive, not decorative)
-->
### 3.4 Focus Management
{{FOCUS_MANAGEMENT}}
<!-- Example:
- Focus visible on all interactive elements (ring-2 ring-primary)
- Focus returns to trigger after modal close
- Error messages announced to screen readers (aria-live="polite")
- Skip navigation links for keyboard users
-->
---
## 4. Branding & Visual Identity
### 4.1 Logo Usage
{{LOGO_USAGE}}
<!-- Example:
- Primary logo (full color) on light backgrounds
- Secondary logo (monochrome white) on dark backgrounds
- Minimum size: 32px height (digital), 0.5in (print)
- Clear space: Logo height on all sides
- Never stretch, skew, or rotate logo
-->
### 4.2 Imagery Guidelines
{{IMAGERY_GUIDELINES}}
<!-- Example:
- Hero images: 16:9 aspect ratio, min 1920x1080px
- Product photos: 1:1 aspect ratio, min 800x800px
- Illustrations: Flat design style, minimalist, 2-3 color palette
- Image optimization: WebP format, lazy loading, responsive srcset
- Stock photos: Professional, diverse, authentic (avoid clichés)
-->
### 4.3 Iconography
{{ICONOGRAPHY}}
<!-- Example:
- Icon library: Heroicons (outline for UI, solid for emphasis)
- Sizes: 16px (inline), 24px (buttons), 32px (features), 48px (headers)
- Style: Outline (2px stroke), consistent visual weight
- Color: Inherit text color or use semantic colors
-->
---
## 5. Page Layout Patterns
### 5.1 {{PAGE_TYPE_1}}
{{PAGE_LAYOUT_1}}
<!-- Example: Homepage
- Hero section: Full-width, py-20, bg-gradient, centered CTA
- Features grid: 3-column (desktop), 1-column (mobile), gap-8
- CTA section: bg-primary, text-white, py-16, centered
- Footer: 4-column links (desktop), stacked (mobile)
-->
### 5.2 {{PAGE_TYPE_2}}
{{PAGE_LAYOUT_2}}
<!-- Example: Dashboard
- Fixed header: h-16, shadow-sm
- Sidebar: w-64 (desktop), hidden (mobile, toggle button)
- Main content: Filters bar → KPI cards (4-column) → Charts grid (2-column) → Data table
- Mobile: Bottom navigation, stacked KPI cards
-->
### 5.3 {{PAGE_TYPE_3}}
{{PAGE_LAYOUT_3}}
<!-- Example: Form page
- Centered narrow container (max-w-2xl)
- Progress indicator (multi-step forms)
- Section dividers with headings
- Action buttons: Right-aligned, primary + secondary
-->
---
## 6. Internationalization (if applicable)
{{I18N_GUIDELINES}}
<!-- Example:
- Language toggle: Top-right header, flag icons + text
- RTL support: Arabic/Hebrew layouts (flex-row-reverse)
- Date/time formatting: Intl.DateTimeFormat API
- Number formatting: Intl.NumberFormat (1,234.56 vs 1.234,56)
- Text expansion: Allow 30% growth for translations (German, Finnish)
- Font fallbacks: Sans-serif for Arabic (Noto Sans Arabic), Cyrillic (Roboto)
-->
---
## 7. Maintenance
**Last Updated:** {{DATE}}
**Update Triggers:**
- New component added to design system
- Brand refresh or logo change
- Accessibility audit findings
- Design system library update (Material UI, Ant Design, etc.)
- Responsive breakpoint changes
- Color palette modifications
**Verification:**
- [ ] All components documented with examples
- [ ] Color contrast ratios WCAG AA compliant (4.5:1 text, 3:1 UI)
- [ ] Typography scale consistent across platform
- [ ] Accessibility guidelines up to date
- [ ] Responsive behaviors tested on all breakpoints
- [ ] Logo usage rules followed
---
**Version:** 1.0.0
**Template Last Updated:** 2025-11-16

168
skills/ln-114-project-docs-creator/references/templates/requirements_template.md Normal file
View File

@@ -0,0 +1,168 @@
# Requirements Specification: {{PROJECT_NAME}}
**Document Version:** 1.0
**Date:** {{DATE}}
**Status:** {{STATUS}}
**Standard Compliance:** ISO/IEC/IEEE 29148:2018
<!-- SCOPE: Functional requirements (FR-XXX-NNN) with MoSCoW prioritization, acceptance criteria, constraints, assumptions, traceability ONLY. -->
<!-- DO NOT add here: NFR (removed completely per project policy), Tech stack → tech_stack.md, Database → database_schema.md, API → api_spec.md, Design system → design_guidelines.md, Operations → runbook.md, Architecture → architecture.md, Implementation → technical_specification.md -->
---
## 1. Introduction
### 1.1 Purpose
This document specifies the functional requirements for {{PROJECT_NAME}}.
### 1.2 Scope
{{PROJECT_SCOPE}}
<!-- Example: E-commerce platform for retail sales. IN SCOPE: Product catalog, shopping cart, checkout, user accounts, order management. OUT OF SCOPE: Warehouse management, shipping logistics, third-party marketplace integration -->
### 1.3 Intended Audience
- Development Team
- QA Team
- DevOps Team
- Technical Writers
- System Architects
### 1.4 References
- Project Charter: {{PROJECT_CHARTER_LINK}}
- Architecture Document: {{ARCHITECTURE_DOC_LINK}}
- Definition of Done: {{DOD_LINK}}
---
## 2. Overall Description
### 2.1 Product Perspective
{{PRODUCT_PERSPECTIVE}}
<!-- Example: Web-based SaaS application replacing legacy desktop system. Interfaces with existing CRM (Salesforce), Payment Gateway (Stripe), Email Service (SendGrid). Deployed on AWS cloud infrastructure -->
### 2.2 User Classes and Characteristics
{{USER_CLASSES}}
<!-- Example: 1. End Customers (tech-savvy, mobile-first, 18-45 age), 2. Admin Users (tech-proficient, desktop, content management), 3. Support Team (moderate tech skills, tickets + reports), 4. API Consumers (developers, programmatic access) -->
### 2.3 Operating Environment
{{OPERATING_ENVIRONMENT}}
<!-- Example: Client: Modern web browsers (Chrome/Firefox/Safari/Edge last 2 versions), Mobile (iOS 14+, Android 10+). Server: AWS (Node.js 18+, PostgreSQL 15, Redis 7), Docker containers, Kubernetes orchestration -->
---
## 3. Functional Requirements
### 3.1 User Management
{{FR_USER_MANAGEMENT}}
<!-- Example: FR-UM-001 (MUST): Users shall register with email+password. FR-UM-002 (MUST): Users shall login with OAuth2 (Google/GitHub). FR-UM-003 (SHOULD): Users shall reset password via email link. FR-UM-004 (MUST): Admins shall manage user roles (Admin/Editor/Viewer) -->
### 3.2 [Feature Group 2]
{{FR_FEATURE_GROUP_2}}
<!-- Example: FR-PC-001 (MUST): System shall display product catalog with search/filter. FR-PC-002 (MUST): Users shall add products to cart. FR-PC-003 (SHOULD): System shall recommend related products -->
### 3.3 [Feature Group 3]
{{FR_FEATURE_GROUP_3}}
<!-- Example: FR-CHK-001 (MUST): Users shall checkout with Stripe payment. FR-CHK-002 (MUST): System shall send order confirmation email. FR-CHK-003 (COULD): Users shall save payment methods for reuse -->
---
## 4. Acceptance Criteria (High-Level)
{{HIGH_LEVEL_ACCEPTANCE_CRITERIA}}
<!-- Example:
1. All MUST functional requirements implemented and passing tests
2. All SHOULD functional requirements reviewed and prioritized
3. All critical user journeys end-to-end tested
4. Acceptance criteria verified for each requirement
5. Traceability matrix complete (FR → Epic → Story → Test Case)
-->
---
## 5. Constraints
### 5.1 Technical Constraints
{{TECHNICAL_CONSTRAINTS}}
<!-- Example: Languages: TypeScript/Node.js (team expertise), Database: PostgreSQL 12 (upgrade planned Q2 2025), Cloud: AWS only (company standard), API: RESTful (no GraphQL this release), Legacy integration: SAP SOAP API (max 10 req/sec) -->
### 5.2 Regulatory Constraints
{{REGULATORY_CONSTRAINTS}}
<!-- Example: GDPR (EU users): Right to erasure, data portability. PCI DSS (payment): Cannot store CVV, encrypted card data. SOC 2: Annual audit required. Data residency: EU data must stay in eu-central-1 region -->
---
## 6. Assumptions and Dependencies
### 6.1 Assumptions
{{ASSUMPTIONS}}
<!-- Example: 1. Users have stable internet (>1 Mbps), 2. Third-party APIs (Stripe, SendGrid) maintain 99.9% uptime, 3. Team size remains 11 people through Year 1, 4. AWS infrastructure scales as needed, 5. Users accept cookies (session management) -->
### 6.2 Dependencies
{{DEPENDENCIES}}
<!-- Example: 1. Stripe API (payment processing), 2. SendGrid API (email delivery), 3. AWS services (ECS, RDS, S3, CloudFront), 4. Salesforce integration (customer sync), 5. DNS provider (Route 53), 6. SSL certificates (ACM) -->
---
## 7. Requirements Traceability
| Requirement ID | Epic | User Story | Test Case | Status |
|---------------|------|------------|-----------|--------|
| FR-UM-001 | Epic-001 | US-001 | TC-001 | {{STATUS}} |
<!-- Example: FR-UM-001 (User Registration) | EP-1 User Management | US-1 Email signup | TC-1 Register with valid email | Implemented -->
---
## 8. Glossary
| Term | Definition |
|------|------------|
| {{TERM_1}} | {{DEFINITION_1}} |
<!-- Example: SLA | Service Level Agreement - contractual uptime commitment (99.9%) | MTTR | Mean Time To Recovery - average time to restore service after failure | p95 | 95th percentile - 95% of requests faster than this value -->
---
## 9. Appendices
### Appendix A: MoSCoW Prioritization Summary
- **MUST have**: {{MUST_COUNT}} requirements
- **SHOULD have**: {{SHOULD_COUNT}} requirements
- **COULD have**: {{COULD_COUNT}} requirements
- **WON'T have (this release)**: {{WONT_COUNT}} requirements
<!-- Example: MUST: 45 (75%), SHOULD: 12 (20%), COULD: 3 (5%), WON'T: 8 (deferred to v2.0) -->
### Appendix B: References
1. ISO/IEC/IEEE 29148:2018 - Systems and software engineering
2. OWASP ASVS (Application Security Verification Standard)
3. WCAG 2.1 (Web Content Accessibility Guidelines)
---
## Maintenance
**Last Updated:** {{DATE}}
**Update Triggers:**
- New functional requirements identified during development
- New constraints or dependencies discovered
- Stakeholder feedback on requirements clarity
- Post-release feedback requiring requirement modifications
- MoSCoW prioritization changes
**Verification:**
- [ ] All FR-XXX-NNN requirements have acceptance criteria
- [ ] All FR-XXX-NNN requirements have MoSCoW priority (MUST/SHOULD/COULD/WON'T)
- [ ] Traceability matrix links requirements to epics/stories
- [ ] No orphaned requirements (all linked to business value)
- [ ] All placeholders replaced with actual content
---
## Revision History
| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.0 | {{DATE}} | {{AUTHOR}} | Initial version |
---
**Version:** 3.0.0 (BREAKING: NFR sections removed completely per project policy)
**Template Last Updated:** 2025-11-16

632
skills/ln-114-project-docs-creator/references/templates/runbook_template.md Normal file
View File

@@ -0,0 +1,632 @@
# Operations Runbook: {{PROJECT_NAME}}
**Document Version:** 1.0
**Date:** {{DATE}}
**Status:** {{STATUS}}
<!-- SCOPE: ALL operational procedures (local development setup, Docker commands, environment variables, testing commands, build/deployment, production operations, troubleshooting, SSH access, logs, restart procedures) ONLY. -->
<!-- DO NOT add here: Architecture patterns → architecture.md, Tech stack versions → tech_stack.md, Database schema → database_schema.md, API endpoints → api_spec.md, Testing strategy → tests/README.md, Design system → design_guidelines.md, Requirements → requirements.md -->
---
## 1. Overview
### 1.1 Purpose
This runbook provides step-by-step operational procedures for {{PROJECT_NAME}} across all environments: local development, testing, and production.
### 1.2 Quick Links
- Architecture: {{ARCHITECTURE_LINK}}
- Tech Stack: {{TECH_STACK_LINK}}
- API Spec: {{API_SPEC_LINK}}
- Database Schema: {{DATABASE_SCHEMA_LINK}}
### 1.3 Key Contacts
{{KEY_CONTACTS}}
<!-- Example:
| Role | Name | Contact | Availability |
|------|------|---------|--------------|
| DevOps Lead | John Doe | john@example.com | 24/7 on-call |
| Tech Lead | Jane Smith | jane@example.com | Mon-Fri 9-6 |
| DBA | Bob Johnson | bob@example.com | Mon-Fri 9-5 |
-->
---
## 2. Prerequisites
### 2.1 Required Tools
{{REQUIRED_TOOLS}}
<!-- Example:
| Tool | Version | Installation |
|------|---------|--------------|
| Docker | 24.0+ | https://docs.docker.com/get-docker/ |
| Docker Compose | 2.20+ | Included with Docker Desktop |
| Node.js | 20.x LTS | https://nodejs.org/ (for local npm scripts) |
| Git | 2.40+ | https://git-scm.com/ |
-->
### 2.2 Access Requirements
{{ACCESS_REQUIREMENTS}}
<!-- Example:
- GitHub repository access (read for development, write for deployment)
- Production SSH keys (request from DevOps lead)
- Database credentials (stored in 1Password vault "ProjectName")
- AWS Console access (IAM role: Developer)
- VPN access for production (if required)
-->
### 2.3 Environment Variables
See [Appendix A: Environment Variables](#appendix-a-environment-variables-reference) for complete reference.
---
## 3. Local Development
### 3.1 Initial Setup
```bash
# Clone repository
git clone https://github.com/org/{{PROJECT_NAME}}.git
cd {{PROJECT_NAME}}
# Copy environment template
cp .env.example .env
# Edit .env with your credentials
# See Appendix A for required variables
# Build and start services
docker compose up -d
# Wait for services to be ready (check logs)
docker compose logs -f app
```
**Expected output:**
```
app-1 | Server started on port 3000
db-1 | database system is ready to accept connections
```
### 3.2 Docker Commands
**Start all services:**
```bash
docker compose up -d
```
**Stop all services:**
```bash
docker compose down
```
**Rebuild after code changes:**
```bash
docker compose down
docker compose build --no-cache app
docker compose up -d
```
**View logs:**
```bash
# All services
docker compose logs -f
# Specific service
docker compose logs -f app
# Last 100 lines
docker compose logs --tail 100 app
```
**Exec into running container:**
```bash
docker compose exec app sh
# or
docker compose exec app bash
```
**Restart specific service:**
```bash
docker compose restart app
```
### 3.3 Database Operations (Local)
**Run migrations:**
```bash
docker compose exec app npm run migrate
# Or using Prisma
docker compose exec app npx prisma migrate dev
```
**Seed database:**
```bash
docker compose exec app npm run seed
```
**Reset database (⚠️ DESTRUCTIVE):**
```bash
docker compose down
docker volume rm {{PROJECT_NAME}}_postgres_data
docker compose up -d
docker compose exec app npm run migrate
docker compose exec app npm run seed
```
**Database shell:**
```bash
# PostgreSQL
docker compose exec db psql -U {{DB_USER}} -d {{DB_NAME}}
# MySQL
docker compose exec db mysql -u {{DB_USER}} -p{{DB_PASSWORD}} {{DB_NAME}}
```
### 3.4 Common Development Tasks
**Install dependencies (after package.json changes):**
```bash
docker compose down
docker compose build app
docker compose up -d
```
**Run linter:**
```bash
docker compose exec app npm run lint
# Fix automatically
docker compose exec app npm run lint:fix
```
**Format code:**
```bash
docker compose exec app npm run format
```
**Check syntax (TypeScript):**
```bash
docker compose exec app npm run type-check
```
---
## 4. Testing
### 4.1 Run All Tests
```bash
# Using docker-compose.test.yml
docker compose -f docker-compose.test.yml up --abort-on-container-exit
```
### 4.2 Run Specific Test Types
**Unit tests:**
```bash
docker compose exec app npm run test:unit
# Watch mode
docker compose exec app npm run test:unit:watch
```
**Integration tests:**
```bash
docker compose exec app npm run test:integration
```
**E2E tests:**
```bash
# Start app first
docker compose up -d
# Run E2E
docker compose exec app npm run test:e2e
```
### 4.3 Test Coverage
```bash
docker compose exec app npm run test:coverage
# Open coverage report
open coverage/index.html
```
### 4.4 Debug Tests
```bash
# Run single test file
docker compose exec app npm test -- path/to/test.spec.ts
# Run with debugging
docker compose exec app node --inspect-brk=0.0.0.0:9229 node_modules/.bin/jest
```
---
## 5. Build & Deployment
### 5.1 Build for Production
```bash
# Build production image
docker build -t {{PROJECT_NAME}}:{{VERSION}} .
# Test production build locally
docker run -p 3000:3000 --env-file .env.production {{PROJECT_NAME}}:{{VERSION}}
```
### 5.2 Deployment to Production
{{DEPLOYMENT_PROCEDURE}}
<!-- Example:
**Prerequisites:**
- [ ] All tests passing (CI/CD green)
- [ ] Code reviewed and approved
- [ ] Database migrations tested in staging
- [ ] Backup created
**Deployment steps:**
```bash
# 1. SSH to production server
ssh production-server
# 2. Navigate to project directory
cd /opt/{{PROJECT_NAME}}
# 3. Pull latest code
git pull origin main
# 4. Backup database
./scripts/backup-db.sh
# 5. Stop services
docker compose down
# 6. Rebuild images
docker compose build --no-cache
# 7. Run migrations
docker compose run --rm app npm run migrate
# 8. Start services
docker compose up -d
# 9. Verify deployment
docker compose logs -f app
curl http://localhost:3000/health
```
**Rollback procedure (if deployment fails):**
```bash
# 1. Rollback code
git reset --hard HEAD~1
# 2. Restore database (if migrations ran)
./scripts/restore-db.sh {{BACKUP_FILE}}
# 3. Restart services
docker compose down && docker compose up -d
```
-->
---
## 6. Production Operations
### 6.1 SSH Access
**SSH to production server:**
```bash
ssh {{PRODUCTION_USER}}@{{PRODUCTION_HOST}}
# Or with SSH key
ssh -i ~/.ssh/{{PROJECT_NAME}}_prod.pem {{PRODUCTION_USER}}@{{PRODUCTION_HOST}}
```
**SSH via jump host (if behind VPN):**
```bash
ssh -J {{JUMP_HOST}} {{PRODUCTION_USER}}@{{PRODUCTION_HOST}}
```
### 6.2 Health Checks
**Check application status:**
```bash
# Health endpoint
curl http://localhost:3000/health
# Expected response:
# {"status": "ok", "uptime": 123456, "timestamp": "2024-01-01T00:00:00Z"}
```
**Check service status:**
```bash
docker compose ps
# Expected output:
# NAME STATUS PORTS
# app-1 Up 5 minutes 0.0.0.0:3000->3000/tcp
# db-1 Up 5 minutes 5432/tcp
# cache-1 Up 5 minutes 6379/tcp
```
**Check resource usage:**
```bash
docker stats
# Or specific container
docker stats app-1
```
### 6.3 Monitoring & Logs
**View logs:**
```bash
# Real-time logs (all services)
docker compose logs -f
# Last 500 lines from app
docker compose logs --tail 500 app
# Logs from specific time
docker compose logs --since 2024-01-01T00:00:00 app
# Save logs to file
docker compose logs --no-color app > app-logs-$(date +%Y%m%d).log
```
**Search logs:**
```bash
# Find errors
docker compose logs app | grep ERROR
# Find specific request
docker compose logs app | grep "request_id=123"
```
**Log rotation:**
{{LOG_ROTATION}}
<!-- Example: Docker logs automatically rotate at 100MB, keep last 3 files. Manual rotation: `docker compose down && docker compose up -d` -->
### 6.4 Common Maintenance Tasks
**Restart application (zero downtime):**
```bash
docker compose up -d --no-deps --force-recreate app
```
**Clear cache:**
```bash
docker compose exec cache redis-cli FLUSHALL
```
**Database backup:**
```bash
# PostgreSQL
docker compose exec db pg_dump -U {{DB_USER}} {{DB_NAME}} > backup-$(date +%Y%m%d-%H%M%S).sql
# MySQL
docker compose exec db mysqldump -u {{DB_USER}} -p{{DB_PASSWORD}} {{DB_NAME}} > backup-$(date +%Y%m%d-%H%M%S).sql
```
**Database restore:**
```bash
# PostgreSQL
cat backup-20240101-120000.sql | docker compose exec -T db psql -U {{DB_USER}} {{DB_NAME}}
# MySQL
cat backup-20240101-120000.sql | docker compose exec -T db mysql -u {{DB_USER}} -p{{DB_PASSWORD}} {{DB_NAME}}
```
**Update dependencies:**
```bash
# Update package.json
docker compose exec app npm update
# Rebuild image
docker compose down
docker compose build --no-cache app
docker compose up -d
```
---
## 7. Troubleshooting
### 7.1 Common Issues
#### Issue 1: Application won't start
**Symptoms:**
```
app-1 | Error: Cannot connect to database
app-1 | Error: ECONNREFUSED
```
**Diagnosis:**
```bash
# Check if database is running
docker compose ps db
# Check database logs
docker compose logs db
# Test database connection
docker compose exec app nc -zv db 5432
```
**Resolution:**
```bash
# Restart database
docker compose restart db
# Wait for database to be ready
docker compose logs -f db
# Look for: "database system is ready to accept connections"
# Restart app
docker compose restart app
```
---
#### Issue 2: Out of disk space
**Symptoms:**
```
Error: no space left on device
```
**Diagnosis:**
```bash
df -h
docker system df
```
**Resolution:**
```bash
# Remove unused Docker resources
docker system prune -a
# Remove specific volumes (⚠️ DESTRUCTIVE)
docker volume rm {{PROJECT_NAME}}_postgres_data
# Remove old log files
find /var/log -name "*.log" -mtime +30 -delete
```
---
#### Issue 3: {{ISSUE_3_NAME}}
{{ISSUE_3_TROUBLESHOOTING}}
<!-- Add project-specific common issues -->
---
### 7.2 Emergency Procedures
**Production outage:**
```bash
# 1. Check health status
curl http://localhost:3000/health
# 2. Check logs for errors
docker compose logs --tail 200 app | grep ERROR
# 3. Restart services
docker compose restart
# 4. If restart fails, rollback
git reset --hard HEAD~1
docker compose down && docker compose up -d
# 5. Notify team (Slack/PagerDuty)
```
**Database corruption:**
```bash
# 1. Stop application
docker compose stop app
# 2. Restore from latest backup
./scripts/restore-db.sh {{LATEST_BACKUP}}
# 3. Verify data integrity
docker compose exec db psql -U {{DB_USER}} -d {{DB_NAME}} -c "SELECT COUNT(*) FROM users;"
# 4. Restart application
docker compose start app
```
---
## 8. Appendices
### Appendix A: Environment Variables Reference
**Required variables:**
| Variable | Example | Description |
|----------|---------|-------------|
| `DATABASE_URL` | `postgresql://user:pass@db:5432/myapp` | Database connection string |
| `REDIS_URL` | `redis://cache:6379` | Cache connection string |
| `API_KEY` | `sk_live_abc123...` | External API key (e.g., Stripe) |
| `JWT_SECRET` | `random_secret_key` | JWT signing secret |
| `NODE_ENV` | `development` or `production` | Environment mode |
**Optional variables:**
| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | `3000` | Application port |
| `LOG_LEVEL` | `info` | Logging verbosity (debug/info/warn/error) |
| `RATE_LIMIT` | `100` | API rate limit (requests/minute) |
---
### Appendix B: Service Dependencies
{{SERVICE_DEPENDENCIES}}
<!-- Example:
**Internal dependencies:**
- app → db (PostgreSQL 16)
- app → cache (Redis 7)
- app → queue (RabbitMQ 3.12)
**External dependencies:**
- Stripe API (https://api.stripe.com)
- SendGrid API (https://api.sendgrid.com)
- AWS S3 (file storage)
**Health check URLs:**
- App: http://localhost:3000/health
- Database: `docker compose exec db pg_isready`
- Cache: `docker compose exec cache redis-cli ping`
-->
---
### Appendix C: Port Mapping
{{PORT_MAPPING}}
<!-- Example:
| Service | Container Port | Host Port | Description |
|---------|----------------|-----------|-------------|
| app | 3000 | 3000 | Application HTTP |
| db | 5432 | 5432 | PostgreSQL |
| cache | 6379 | 6379 | Redis |
| adminer | 8080 | 8080 | Database admin UI |
-->
---
## 9. Maintenance
**Last Updated:** {{DATE}}
**Update Triggers:**
- New deployment procedures
- Infrastructure changes (new services, ports)
- New operational commands
- Troubleshooting scenarios discovered
- Environment variable changes
- SSH access changes
**Verification:**
- [ ] All commands tested in staging
- [ ] SSH access verified
- [ ] Health check procedures validated
- [ ] Backup/restore procedures tested
- [ ] Emergency procedures reviewed
- [ ] Contact information current
---
**Version:** 1.0.0
**Template Last Updated:** 2025-11-16

249
skills/ln-114-project-docs-creator/references/templates/tech_stack_template.md Normal file
View File

@@ -0,0 +1,249 @@
# Technology Stack: {{PROJECT_NAME}}
**Document Version:** 1.0
**Date:** {{DATE}}
**Status:** {{STATUS}}
<!-- SCOPE: Technology stack (specific versions, libraries, frameworks), Docker configuration (Dockerfile, docker-compose.yml), development tools, naming conventions ONLY. -->
<!-- DO NOT add here: API endpoints → api_spec.md, Database schema → database_schema.md, Architecture patterns → architecture.md, Requirements → requirements.md, Deployment procedures → runbook.md, Design system → design_guidelines.md -->
---
## 1. Introduction
### 1.1 Purpose
This document specifies the technology stack, frameworks, libraries, and tools used in {{PROJECT_NAME}}.
### 1.2 Scope
{{SCOPE}}
<!-- Example: Full-stack web application. IN SCOPE: Frontend (React), Backend (Node.js/Express), Database (PostgreSQL), Cache (Redis), Docker setup. OUT OF SCOPE: Infrastructure provisioning (see runbook.md), API contracts (see api_spec.md) -->
---
## 2. Technology Stack
### 2.1 Stack Overview
| Layer | Technology | Version | Rationale | ADR |
|-------|------------|---------|-----------|-----|
| **Frontend** | {{FRONTEND_FRAMEWORK}} | {{FRONTEND_VERSION}} | {{FRONTEND_RATIONALE}} | {{FRONTEND_ADR_LINK}} |
| **Backend** | {{BACKEND_FRAMEWORK}} | {{BACKEND_VERSION}} | {{BACKEND_RATIONALE}} | {{BACKEND_ADR_LINK}} |
| **Database** | {{DATABASE}} | {{DATABASE_VERSION}} | {{DATABASE_RATIONALE}} | {{DATABASE_ADR_LINK}} |
| **Cache** | {{CACHE}} | {{CACHE_VERSION}} | {{CACHE_RATIONALE}} | {{CACHE_ADR_LINK}} |
| **Message Queue** | {{QUEUE}} | {{QUEUE_VERSION}} | {{QUEUE_RATIONALE}} | {{QUEUE_ADR_LINK}} |
| **Testing** | {{TEST_FRAMEWORK}} | {{TEST_VERSION}} | {{TEST_RATIONALE}} | {{TEST_ADR_LINK}} |
| **DevOps** | {{DEVOPS_TOOLS}} | {{DEVOPS_VERSION}} | {{DEVOPS_RATIONALE}} | {{DEVOPS_ADR_LINK}} |
<!-- Example:
| Frontend | React | 18.2.0 | Component-based UI, large ecosystem, TypeScript support | [ADR-003](../reference/adrs/adr-003-react.md) |
| Backend | Node.js + Express | 20.x + 4.18.x | JavaScript full-stack, async/await, vast npm ecosystem | [ADR-001](../reference/adrs/adr-001-nodejs.md) |
| Database | PostgreSQL | 16.x | ACID compliance, JSON support, mature ecosystem | [ADR-002](../reference/adrs/adr-002-postgresql.md) |
| Cache | Redis | 7.x | In-memory performance, pub/sub, session storage | [ADR-004](../reference/adrs/adr-004-redis.md) |
| Queue | RabbitMQ | 3.12.x | Reliable message delivery, dead letter queues | [ADR-005](../reference/adrs/adr-005-rabbitmq.md) |
| Testing | Jest + Playwright | 29.x + 1.40.x | Unit testing (Jest), E2E testing (Playwright) | [ADR-006](../reference/adrs/adr-006-testing.md) |
| DevOps | Docker + GitHub Actions | 24.x + latest | Containerization, CI/CD automation | [ADR-007](../reference/adrs/adr-007-devops.md) |
-->
### 2.2 Key Libraries & Dependencies
**Frontend:**
{{FRONTEND_LIBRARIES}}
<!-- Example: React Router (6.x) - routing, Tailwind CSS (3.x) - styling, Axios (1.x) - HTTP client, React Query (5.x) - data fetching -->
**Backend:**
{{BACKEND_LIBRARIES}}
<!-- Example: Prisma (5.x) - ORM, bcrypt (5.x) - password hashing, jsonwebtoken (9.x) - JWT auth, winston (3.x) - logging -->
**Common:**
{{COMMON_LIBRARIES}}
<!-- Example: TypeScript (5.x) - type safety, ESLint (8.x) - linting, Prettier (3.x) - code formatting -->
---
## 3. Docker Development Environment
### 3.1 Dockerfile
```dockerfile
{{DOCKERFILE_CONTENT}}
```
<!-- Example:
```dockerfile
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 3000
CMD ["npm", "start"]
```
-->
### 3.2 docker-compose.yml (Development)
```yaml
{{DOCKER_COMPOSE_DEV}}
```
<!-- Example:
```yaml
version: '3.8'
services:
app:
build: .
ports:
- "3000:3000"
environment:
DATABASE_URL: postgresql://user:password@db:5432/myapp
REDIS_URL: redis://cache:6379
depends_on:
- db
- cache
db:
image: postgres:16-alpine
environment:
POSTGRES_USER: user
POSTGRES_PASSWORD: password
POSTGRES_DB: myapp
volumes:
- postgres_data:/var/lib/postgresql/data
cache:
image: redis:7-alpine
ports:
- "6379:6379"
volumes:
postgres_data:
```
-->
### 3.3 docker-compose.test.yml (Testing)
```yaml
{{DOCKER_COMPOSE_TEST}}
```
<!-- Example:
```yaml
version: '3.8'
services:
test:
build: .
command: npm run test
environment:
DATABASE_URL: postgresql://user:password@db-test:5432/myapp_test
depends_on:
- db-test
tmpfs:
- /app/coverage
db-test:
image: postgres:16-alpine
environment:
POSTGRES_USER: user
POSTGRES_PASSWORD: password
POSTGRES_DB: myapp_test
```
-->
---
## 4. Development Tools
### 4.1 Required Tools
| Tool | Version | Purpose | Installation |
|------|---------|---------|--------------|
| Node.js | {{NODE_VERSION}} | Runtime environment | https://nodejs.org/ |
| Docker | 24.0+ | Container runtime | https://docs.docker.com/get-docker/ |
| Git | 2.40+ | Version control | https://git-scm.com/ |
| {{IDE}} | Latest | Code editor | {{IDE_LINK}} |
<!-- Example:
| Node.js | 20.x LTS | Runtime environment | https://nodejs.org/ |
| Docker | 24.0+ | Container runtime | https://docs.docker.com/get-docker/ |
| Git | 2.40+ | Version control | https://git-scm.com/ |
| VS Code | Latest | Code editor | https://code.visualstudio.com/ |
-->
### 4.2 VS Code Extensions (Recommended)
{{VSCODE_EXTENSIONS}}
<!-- Example: ESLint, Prettier, Docker, Prisma, Tailwind CSS IntelliSense -->
### 4.3 Linters & Code Quality Tools
| Tool | Version | Purpose | Command | Config File |
|------|---------|---------|---------|-------------|
| {{LINTER_1}} | {{VERSION_1}} | {{PURPOSE_1}} | {{COMMAND_1}} | {{CONFIG_1}} |
<!-- Example:
| ESLint | 9.x | JavaScript/TypeScript linting | `npm run lint` | .eslintrc.js |
| Prettier | 3.x | Code formatting | `npm run format:check` | .prettierrc |
| TypeScript | 5.x | Type checking | `tsc --noEmit` | tsconfig.json |
| Ruff | 0.4.x | Python linting | `ruff check .` | pyproject.toml |
| Stylelint | 16.x | CSS/SCSS linting | `npm run lint:css` | .stylelintrc |
-->
**CI/CD Integration:**
{{CI_LINT_INTEGRATION}}
<!-- Example:
- Pre-commit hook: `npm run lint && npm run format:check`
- GitHub Actions: `npm run lint` in CI workflow
- Required for merge: All linters must pass (0 errors)
-->
**Run All Quality Checks:**
```bash
{{LINT_ALL_COMMAND}}
```
<!-- Example: npm run lint && npm run format:check && tsc --noEmit -->
---
## 5. Naming Conventions
### 5.1 File Naming
{{FILE_NAMING}}
<!-- Example: Components: PascalCase (UserProfile.tsx), Utilities: camelCase (formatDate.ts), Constants: UPPER_SNAKE_CASE (API_ENDPOINTS.ts) -->
### 5.2 Variable Naming
{{VARIABLE_NAMING}}
<!-- Example: camelCase for variables/functions, PascalCase for classes/components, UPPER_SNAKE_CASE for constants -->
### 5.3 Database Naming
{{DATABASE_NAMING}}
<!-- Example: Tables: snake_case plural (user_profiles), Columns: snake_case (first_name), Indexes: idx_table_column -->
---
## 6. Maintenance
**Last Updated:** {{DATE}}
**Update Triggers:**
- Technology version upgrade (major/minor releases)
- New library added to dependencies
- Docker configuration changes
- Development tool updates
**Verification:**
- [ ] All versions match package.json/Dockerfile
- [ ] ADR links valid and point to correct decisions
- [ ] Docker compose files tested and working
- [ ] All listed tools accessible with installation links
---
**Version:** 1.0.0
**Template Last Updated:** 2025-11-16

785
skills/ln-115-presentation-creator/SKILL.md Normal file
View File

@@ -0,0 +1,785 @@
---
name: ln-115-presentation-creator
description: Builds interactive HTML presentation with 6 tabs (Overview, Requirements, Architecture/C4, Tech Spec, Roadmap, Guides). Creates presentation/README.md hub. Worker under ln-110-documents-pipeline.
---
# HTML Presentation Builder
This skill creates an interactive, self-contained HTML presentation from existing project documentation. It transforms Markdown documents into a professional, navigable web presentation with diagrams, collapsible sections, and modern UI.
## When to Use This Skill
**This skill is a WORKER** invoked by **ln-110-documents-pipeline** orchestrator OR used standalone.
Use this skill when:
- Building HTML presentation from existing documentation
- Rebuilding presentation after documentation updates
- Creating standalone presentation for sharing (no full documentation setup needed)
- Validating that source documentation is ready for presentation generation
**Part of workflow**: ln-110-documents-pipeline → ln-111-root-docs-creator → ln-112-reference-docs-creator → ln-113-tasks-docs-creator → ln-114-project-docs-creator → **ln-115-presentation-creator**
**Prerequisites**: Existing documentation in `docs/` directory with **required files**:
- `docs/project/requirements.md` (REQUIRED)
- `docs/project/architecture.md` (REQUIRED)
- `docs/project/tech_stack.md` (REQUIRED)
**Optional files** (enhance presentation but not blocking):
- `docs/project/api_spec.md`, `database_schema.md`, `design_guidelines.md`, `runbook.md`
- `docs/reference/adrs/*.md` (ADRs with Category: Strategic|Technical)
- `docs/reference/guides/*.md` (How-to guides)
- `docs/tasks/kanban_board.md` (Epic Story Counters for Roadmap)
## How It Works
The skill follows a **7-phase workflow**: READ DOCS → VALIDATE SOURCE EXISTS → VALIDATE SOURCE QUALITY → CREATE DIR → COPY TEMPLATES → INJECT CONTENT → BUILD HTML.
**Phase 1: READ DOCS** - Load all project documentation from docs/
**Phase 2: VALIDATE SOURCE EXISTS** - Check required files exist (requirements.md, architecture.md, tech_stack.md), warn if optional missing
**Phase 3: VALIDATE SOURCE QUALITY** - Check diagrams, placeholders, content length (read-only validation)
**Phase 4: CREATE DIR** - Create presentation/ directory + README.md navigation hub
**Phase 5: COPY TEMPLATES** - Copy HTML/CSS/JS templates to assets/
**Phase 6: INJECT CONTENT** - Parse MD docs → replace placeholders in tab files → delete example blocks
**Phase 7: BUILD HTML** - Assemble modular components into standalone presentation_final.html
---
## Phase 1: Read Documentation
**Objective**: Load all project documentation for transformation.
**When to execute**: Always (first phase)
**Process**:
1. **Use docs/ as source**:
- Read documentation from `docs/project/`, `docs/reference/`, `docs/tasks/` directories
- Standard locations created by ln-114, ln-112, ln-113
2. **Read Core MD Documents**:
- `project/requirements.md` - Functional Requirements
- `project/architecture.md` - Architecture design, C4 diagrams
- `project/tech_stack.md` - Technology versions, Docker configuration
- `project/api_spec.md` - API endpoints, authentication (if exists)
- `project/database_schema.md` - Database schema, ER diagrams (if exists)
- `project/design_guidelines.md` - UI/UX design system (if exists)
- `project/runbook.md` - Operational procedures (if exists)
3. **Read ADRs** (if exist):
- `reference/adrs/adr-001-*.md` through `adr-NNN-*.md`
- Parse ADR metadata (status, date, title, Category: Strategic|Technical)
4. **Read Guides** (if exist):
- `reference/guides/*.md` - How-to guides for Guides tab
5. **Read Kanban Board** (if exists):
- `tasks/kanban_board.md` - Epic Story Counters table for Roadmap progress
6. **Extract metadata**:
- Project name, date, version from documents
- Preserve Mermaid diagram blocks
**Output**: Loaded documentation data ready for validation and HTML generation
---
## Phase 2: Validate Source Documentation Exists
**Objective**: Verify that required source documentation exists before building presentation. Prevent building incomplete presentations.
**When to execute**: After Phase 1 (documentation loaded)
**Process**:
### 2.1 Check required files
**REQUIRED** (must exist - block execution if missing):
- ✅ `docs/project/requirements.md`
- ✅ `docs/project/architecture.md`
- ✅ `docs/project/tech_stack.md`
For each required file:
1. Use Glob tool: `pattern: "docs/project/{filename}"`
2. If NOT found:
- Add to missing list
3. If found:
- Check file size > 100 bytes (not empty)
**If ANY required file missing or empty:**
```
❌ ERROR: Cannot build presentation - missing required documentation:
- docs/project/requirements.md [missing/empty]
- docs/project/architecture.md [missing/empty]
Suggestion: Run ln-114-project-docs-creator to create missing files.
STOP execution.
```
### 2.2 Check optional files
**OPTIONAL** (enhance presentation - warn if missing but continue):
- ⚠️ `docs/project/api_spec.md` (for backend projects)
- ⚠️ `docs/project/database_schema.md` (for projects with database)
- ⚠️ `docs/project/design_guidelines.md` (for frontend projects)
- ⚠️ `docs/project/runbook.md` (for operational projects)
For each optional file:
1. Use Glob tool: `pattern: "docs/project/{filename}"`
2. If NOT found:
- Add to optional missing list
**If optional files missing:**
```
⚠ WARN: Optional files missing: [list]
Presentation will have reduced content in some tabs.
Continue execution.
```
### 2.3 Check optional directories
**OPTIONAL directories:**
- `docs/reference/adrs/` - check if any ADR files exist (`adrs/*.md`)
- `docs/reference/guides/` - check if any guide files exist (`guides/*.md`)
- `docs/tasks/kanban_board.md` - check for Roadmap data
For each directory:
1. Use Glob tool to find files
2. If empty/missing:
- Log: `ℹ Optional directory empty: {directory} - related tab will show placeholder`
### 2.4 Report validation summary
Log summary:
```
✓ Source documentation validation completed:
Required files:
- ✅ requirements.md (found, 8.5 KB)
- ✅ architecture.md (found, 15.2 KB)
- ✅ tech_stack.md (found, 3.1 KB)
Optional files:
- ⚠️ api_spec.md (missing - Technical Spec tab will have reduced content)
- ✅ database_schema.md (found, 4.7 KB)
- ⚠️ design_guidelines.md (missing)
Optional directories:
- ✅ adrs/ (5 ADR files found)
- ⚠️ guides/ (empty - Guides tab will show placeholder)
- ✅ kanban_board.md (found - Roadmap will show progress)
```
**Output**: Validation passed (all required files exist) OR error (stop execution)
---
## Phase 3: Validate Source Content Quality
**Objective**: Verify that source docs contain sufficient content for presentation generation. Warn about incomplete content but don't block execution.
**When to execute**: After Phase 2 (source files exist)
**Process**:
### 3.1 Check for Mermaid diagrams
**Required diagrams:**
- `architecture.md` MUST have at least 1 Mermaid diagram (preferably C4 Context)
- `database_schema.md` (if exists) MUST have ER diagram
For each file:
1. Read file content
2. Search for Mermaid code blocks: ` ```mermaid`
3. Count diagrams
**If diagrams missing:**
```
⚠ WARN: Missing diagrams in architecture.md
Expected: At least 1 Mermaid diagram (C4 Context, Container, or Component)
Found: 0 diagrams
Presentation Architecture tab will have incomplete visualization.
Suggestion: Add C4 diagrams to architecture.md before building.
```
### 3.2 Check for placeholders
**Placeholder patterns to detect:**
- `{{PLACEHOLDER}}` (template placeholder)
- `[Add your ...]` (instruction placeholder)
- `TODO:` (incomplete content marker)
For each source file:
1. Read file content
2. Search for placeholder patterns (case-insensitive)
3. Collect matches with line numbers
**If placeholders found:**
```
⚠ WARN: Source docs contain placeholders:
- requirements.md:42 - {{PROJECT_DESCRIPTION}}
- tech_stack.md:15 - [Add your technology rationale]
- api_spec.md:8 - TODO: Add authentication endpoints
Presentation will show incomplete content.
Suggestion: Complete placeholders before building for professional result.
```
### 3.3 Check content length
**Minimum expected lengths:**
- `requirements.md` > 500 words
- `architecture.md` > 1000 words
- `tech_stack.md` > 200 words
For each file:
1. Read file content
2. Count words (split by whitespace, exclude code blocks)
3. Compare to threshold
**If content too short:**
```
⚠ WARN: Sparse content detected:
- requirements.md: 320 words (expected >500)
- tech_stack.md: 150 words (expected >200)
Presentation may look incomplete with thin content.
Suggestion: Expand documentation before building.
```
### 3.4 Auto-fix opportunities
**None** - ln-115 is **read-only** for source docs:
- ❌ Does NOT edit markdown documentation
- ✅ Only READS and TRANSFORMS to HTML
**If issues found:**
```
💡 To fix content issues:
- Run ln-114-project-docs-creator to complete documentation
- Manually edit source files in docs/project/
- Re-run ln-115-presentation-creator after fixes
```
### 3.5 Report content quality summary
Log summary:
```
✓ Content quality validation completed:
Diagrams:
- ✅ architecture.md: 3 Mermaid diagrams found (C4 Context, Container, Component)
- ⚠️ database_schema.md: No ER diagram found
Placeholders:
- ⚠️ Found 2 placeholders in 2 files (see details above)
Content length:
- ✅ requirements.md: 1,250 words
- ✅ architecture.md: 2,100 words
- ⚠️ tech_stack.md: 180 words (expected >200)
Warnings: 3 (non-blocking)
Recommendation: Address warnings for professional result, or continue with current content.
```
**Output**: Content quality report (warnings only, does not block execution)
---
## Phase 4: Create Presentation Directory & README
**Objective**: Setup presentation directory structure and navigation hub.
**When to execute**: After Phase 3 (source validation complete, warnings logged)
**Process**:
1. **Create presentation directory**:
```bash
mkdir -p docs/presentation/
```
2. **Check if presentation/README.md exists**:
- Use Glob tool: `pattern: "docs/presentation/README.md"`
- If file exists:
- Skip creation
- Log: `✓ docs/presentation/README.md already exists (preserved)`
- Proceed to Phase 5
- If NOT exists:
- Continue to step 3
3. **Create presentation/README.md from template**:
- Copy template: `references/presentation_readme_template.md` → `docs/presentation/README.md`
- Replace placeholders:
- `{{PROJECT_NAME}}` — from requirements.md
- `{{LAST_UPDATED}}` — current date (YYYY-MM-DD)
- Content structure:
- **Purpose**: What is this presentation
- **Quick Navigation**: Links to presentation_final.html and assets/
- **Customization Guide**: How to edit source files in assets/
- **Build Instructions**: How to rebuild after changes
- **Maintenance**: When to rebuild, verification checklist
4. **Notify user**:
- If created: `✓ Created docs/presentation/README.md (navigation hub)`
- If skipped: `✓ docs/presentation/README.md already exists (preserved)`
**Output**: docs/presentation/README.md (created or existing)
---
## Phase 5: Copy Templates to Project
**Objective**: Copy HTML/CSS/JS templates from skill references/ to presentation directory.
**When to execute**: After Phase 4 (presentation directory exists)
**Process**:
1. **Check if assets exist**:
- Use Glob tool: `pattern: "docs/presentation/assets/"`
- If `docs/presentation/assets/` exists:
- Skip copying (user may have customized files)
- Log: `✓ Presentation assets already exist - preserving user customizations`
- Proceed to Phase 6
- If NOT exists:
- Continue to step 2
2. **Copy template files**:
```bash
cp references/presentation_template.html → docs/presentation/assets/
cp references/styles.css → docs/presentation/assets/
cp references/scripts.js → docs/presentation/assets/
cp references/build-presentation.js → docs/presentation/assets/
cp -r references/tabs/ → docs/presentation/assets/tabs/
```
3. **Verify copied structure**:
```
docs/presentation/assets/
├── presentation_template.html # Base HTML5 + 6 tab navigation
├── styles.css # ~400-500 lines
├── scripts.js # Tab switching + Mermaid init
├── build-presentation.js # Node.js build script
└── tabs/
├── tab_overview.html # Landing page
├── tab_requirements.html # FRs + ADRs
├── tab_architecture.html # C4 diagrams
├── tab_technical_spec.html # API + Data + Deployment
├── tab_roadmap.html # Epic list
└── tab_guides.html # How-to guides
```
**Output**: Template files copied to docs/presentation/assets/ (or skipped if already exist)
**Note**: Templates contain placeholders (`{{VARIABLE_NAME}}`) that will be replaced in Phase 6.
---
## Phase 6: Content Injection & Example Cleanup
**Objective**: Parse MD documentation, inject into HTML templates, and remove example blocks to create project-specific presentation.
**When to execute**: After Phase 5 (templates exist in assets/)
**Process**:
### 6.1 Read and Parse MD Documents
Read and parse the following documentation files (from Phase 1):
1. **requirements.md**: Project name, tagline, business goal, functional requirements, constraints, success criteria
2. **architecture.md**: Architecture diagrams (C4 Context/Container/Component), solution strategy, quality attributes
3. **tech_stack.md**: Technology Stack table (with versions, rationale, ADR links), Docker configuration
4. **api_spec.md** (if exists): API endpoints, authentication methods, error codes
5. **database_schema.md** (if exists): ER diagrams, data dictionary (tables/columns/types)
6. **design_guidelines.md** (if exists): Typography, colors, component library, accessibility
7. **runbook.md** (if exists): Development setup, deployment procedures, troubleshooting
8. **adrs/*.md**: All ADR files (parse title, status, category, content)
9. **kanban_board.md** (if exists): Epic Story Counters table for Roadmap progress
10. **guides/*.md** (if exist): How-to guides for Guides tab
### 6.2 Inject Content into Templates
Replace placeholders in copied template files with parsed content from project documentation.
**Key Placeholders (in tab templates):**
**Overview Tab** (`tab_overview.html`):
- `{{PROJECT_SUMMARY}}` — Problem/Solution/Business Value structure (3 sections)
- `{{TECH_STACK}}` — Technology badges (brief list only)
- `{{STAKEHOLDERS}}` — Stakeholder cards with names and roles
- `{{QUICK_FACTS}}` — Project Status, Total Epics, Deployment Model, Target Platforms
- `{{NAVIGATION_GUIDE}}` — Documentation guide with tab descriptions
**Requirements Tab** (`tab_requirements.html`):
- `{{FUNCTIONAL_REQUIREMENTS}}` — FRs table (ID, Priority, Requirement, Acceptance Criteria)
- `{{ADR_STRATEGIC}}` — Strategic ADRs grouped section with accordion
- `{{ADR_TECHNICAL}}` — Technical ADRs grouped section with accordion
- `{{SUCCESS_CRITERIA}}` — Project success metrics
- **Non-Functional Requirements are banned**: Drop any NFR content found in source docs instead of converting it into tables or IDs
**Architecture Tab** (`tab_architecture.html`):
- `{{C4_CONTEXT}}` — System Context diagram (C4 Level 1)
- `{{C4_CONTAINER}}` — Container diagram (C4 Level 2)
- `{{C4_COMPONENT}}` — Component diagram (C4 Level 3)
- `{{DEPLOYMENT_DIAGRAM}}` — Infrastructure deployment diagram
- `{{ARCHITECTURE_NOTES}}` — Key architecture highlights table
**Technical Spec Tab** (`tab_technical_spec.html`):
- `{{TECH_STACK_TABLE}}` — Full technology stack table with versions and purposes
- `{{API_ENDPOINTS}}` — API endpoints tables (Authentication, Products, Cart, etc.)
- `{{DATA_MODELS}}` — ER diagram + Data dictionary table
- `{{TESTING_STRATEGY}}` — Risk-Based Testing approach and test pyramid
**Roadmap Tab** (`tab_roadmap.html`):
- `{{EPIC_CARDS}}` — All Epic cards with In/Out Scope, Dependencies, Success Criteria, Progress
- `{{OUT_OF_SCOPE_ITEMS}}` — Project-level out-of-scope items with reasons
- `{{ROADMAP_LEGEND}}` — Status badges explanation
**Guides Tab** (`tab_guides.html`):
- `{{GETTING_STARTED}}` — Prerequisites, Installation, Verification
- `{{HOW_TO_GUIDES}}` — Step-by-step how-to guides (from guides/*.md)
- `{{BEST_PRACTICES}}` — Code style, Testing approach, Design patterns
- `{{TROUBLESHOOTING}}` — Common problems and solutions
- `{{CONTRIBUTING}}` — Contributing guidelines
- `{{EXTERNAL_RESOURCES}}` — Links to external documentation
**Placeholder Replacement Logic:**
- Use **Edit** tool to replace `{{PLACEHOLDER}}` → actual content from project docs
- For lists/arrays: generate HTML dynamically (e.g., loop through ADRs, create `<details>` elements)
- For Kanban: parse kanban_board.md → calculate progress % → generate Epic card HTML
- Preserve SCOPE tags in tab files (HTML comments at top)
- Escape special characters to prevent XSS
- Generate valid Mermaid syntax
### 6.3 Delete Example Blocks
**CRITICAL**: Remove all example content blocks to create project-specific presentation.
**Process**:
1. **Search for example markers** in all 6 tab files:
- Look for `<!-- EXAMPLE START: Remove this block after replacing placeholder -->`
- Look for `<!-- EXAMPLE END -->`
2. **Delete example blocks** using Edit tool:
- Remove everything between `<!-- EXAMPLE START -->` and `<!-- EXAMPLE END -->` (inclusive)
- Do this for ALL occurrences across all 6 tab files
- Leave only the actual project content that replaced `{{PLACEHOLDER}}` comments
3. **Validate cleanup**:
- ✅ NO `<!-- EXAMPLE START -->` markers should remain
- ✅ NO `<!-- EXAMPLE END -->` markers should remain
- ✅ NO hardcoded e-commerce examples (John Smith, React 18 badges, Stripe, etc.)
- ✅ Only actual project data should be visible in tab files
**Example transformation:**
**Before (dual-content template):**
```html
<!-- PLACEHOLDER: {{PROJECT_SUMMARY}} -->
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
<div class="project-summary">
<h3>The Problem</h3>
<p>Traditional e-commerce platforms struggle...</p>
</div>
<!-- EXAMPLE END -->
```
**After Step 6.2 (placeholder replaced):**
```html
<div class="project-summary">
<h3>The Problem</h3>
<p>Our healthcare system needs unified patient records...</p>
</div>
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
<div class="project-summary">
<h3>The Problem</h3>
<p>Traditional e-commerce platforms struggle...</p>
</div>
<!-- EXAMPLE END -->
```
**After Step 6.3 (examples deleted):**
```html
<div class="project-summary">
<h3>The Problem</h3>
<p>Our healthcare system needs unified patient records...</p>
</div>
```
**Output**: Clean, project-specific tab files with NO example content, ready for build
---
## Phase 7: Build Final Presentation
**Objective**: Assemble modular components into standalone HTML file.
**When to execute**: After Phase 6 (content injected, examples deleted)
**Process**:
1. **Check if presentation_final.html exists (Auto-rebuild for automation)**:
- Use Glob tool: `pattern: "docs/presentation/presentation_final.html"`
- If file exists:
- **✓ Auto-rebuild** (generated file, safe operation)
- Log: `ℹ Rebuilding presentation_final.html (generated file, safe to rebuild)`
- Continue to step 2
- If NOT exists:
- Log: `Creating presentation_final.html`
- Continue to step 2
**Why auto-rebuild:**
- presentation_final.html is a **generated file** (source of truth: assets/ directory)
- Rebuilding is safe - no data loss (source files preserved in assets/)
- Maintains fully automatic workflow when invoked by ln-110-documents-pipeline
- User customizations in assets/ are preserved (only final HTML is regenerated)
2. **Navigate to presentation assets directory**:
```bash
cd docs/presentation/assets/
```
3. **Run build script**:
```bash
node build-presentation.js
```
4. **Build Script Process**:
- **Step 1**: Read presentation_template.html
- **Step 2**: Read and inline styles.css → `<style>` tag
- **Step 3**: Read and inline scripts.js → `<script>` tag
- **Step 4**: Read all 6 tab files → inject into empty `<div>` containers
- **Step 5**: Replace {{PLACEHOLDERS}} with actual values
- **Step 6**: Write `../presentation_final.html`
5. **Validate Output** (only if file was built):
- Check file size (~120-150 KB expected)
- Verify Mermaid diagrams syntax is valid
- Log: `✓ Build completed successfully`
6. **Notify user**:
- If rebuilt (file existed): `✓ Rebuilt docs/presentation/presentation_final.html (~120-150 KB)`
- If created (file NOT existed): `✓ Created docs/presentation/presentation_final.html (~120-150 KB)`
- Remind: `Test in browser: Double-click to open, or use http-server`
**Output**: docs/presentation/presentation_final.html (self-contained, ~120-150 KB, no external dependencies except Mermaid.js CDN)
**⚠️ Important Note:**
`presentation_final.html` is a **generated file** built from modular source files in `assets/`.
- ❌ **DO NOT edit `presentation_final.html` directly** — changes will be lost on next rebuild
- ✅ **DO edit source files** in `assets/` directory (template, tabs, styles, scripts)
- 🔄 **Rebuild after changes**: `cd assets/ && node build-presentation.js`
---
## Complete Output Structure
```
docs/
├── project/ # Source documentation (input)
│ ├── requirements.md
│ ├── architecture.md
│ ├── tech_stack.md
│ ├── api_spec.md (conditional)
│ ├── database_schema.md (conditional)
│ ├── design_guidelines.md (conditional)
│ └── runbook.md (conditional)
├── reference/ # Source documentation (input)
│ ├── adrs/
│ │ └── *.md (Category: Strategic | Technical)
│ └── guides/
│ └── *.md (optional)
├── tasks/ # Source documentation (input)
│ └── kanban_board.md (Epic Story Counters)
└── presentation/ # Output directory
├── README.md # Navigation hub
├── presentation_final.html # Final standalone HTML (~120-150 KB)
└── assets/ # Modular HTML structure
├── presentation_template.html # Base HTML5 + 6 tabs
├── styles.css # ~400-500 lines
├── scripts.js # Tab switching + Mermaid
├── build-presentation.js # Node.js build script
└── tabs/
├── tab_overview.html # Landing page
├── tab_requirements.html # FRs + ADRs
├── tab_architecture.html # C4 diagrams
├── tab_technical_spec.html # API + Data + Deployment
├── tab_roadmap.html # Epic list
└── tab_guides.html # How-to guides
```
**Note**: Presentation READS from docs/project/, docs/reference/, docs/tasks/ but OUTPUTS to docs/presentation/.
---
## HTML Features
- **Single Source of Truth**: No information duplication - each piece lives in exactly ONE tab
- **Landing Page (Overview)**: Problem/Solution/Business Value, Stakeholders, Documentation Guide, Quick Facts, Tech Stack badges
- **Interactive Navigation**: 6 tabs with SCOPE tags, state persistence (localStorage), smooth transitions
- **Table-Based Layout**: FRs table only (Non-Functional Requirements are forbidden), Architecture highlights table
- **Roadmap Simplified**: Vertical Epic list with In/Out Scope sections, status badges, Dependencies/Success Criteria
- **ADR Organization**: Grouped by category (Strategic/Technical) with accordion, full content inline
- **Diagram Visualization**: Mermaid.js with tab-switch rerender (C4, ER, Sequence, Deployment)
- **Responsive Design**: Mobile-first (320px/768px/1024px+ breakpoints)
- **Collapsible Sections**: Auto-collapse with scroll preservation
- **Modern UI**: Clean professional design, WCAG 2.1 Level AA compliant
- **English Language**: All presentation content in English
---
## Best Practices
### Idempotent Operation
- ✅ Checks file existence before creation (presentation/README.md)
- ✅ Auto-rebuild: Always rebuilds presentation_final.html (generated file)
- ✅ Assets preservation: Skips copying templates if assets/ exists (preserves customizations)
- ✅ Safe re-runs: Can invoke multiple times without data loss
### During Documentation Reading (Phase 1)
- Validate paths: Check docs/ exists before reading
- Graceful degradation: Continue if some files missing (warn user)
- Extract metadata: Pull project name, date, version
- Parse Mermaid blocks: Preserve diagram syntax
### During Source Validation (Phase 2/3)
- **Phase 2**: STOP execution if required files missing (requirements.md, architecture.md, tech_stack.md)
- **Phase 3**: WARN about quality issues but don't block (missing diagrams, placeholders, sparse content)
- Provide actionable suggestions: "Run ln-114 to complete docs"
- Read-only: Never edit source docs
### During Template Copying (Phase 5)
- Check existing assets: Don't overwrite user-customized templates
- Verify directory structure: Ensure tabs/ subdirectory created
- Preserve permissions: Maintain executable permissions for build script
### During Content Injection & Cleanup (Phase 6)
- Preserve Markdown formatting: Convert MD → HTML correctly
- Generate valid Mermaid syntax: Test all diagram syntax
- Escape special characters: Prevent XSS vulnerabilities
- Use semantic HTML: Proper heading hierarchy, ARIA labels
- Preserve SCOPE tags: Keep HTML comments in tab files
- **Complete example cleanup**: Ensure ALL example blocks deleted
- **Verify project-specific content**: NO hardcoded e-commerce examples in final tabs
### During Build (Phase 7)
- Validate Node.js availability: Check `node --version` before running
- Handle errors gracefully: Provide clear error messages
- Test output: Open presentation_final.html to verify rendering
- Size check: Warn if file >200 KB (may indicate issues)
---
## Customization Options
Edit `assets/styles.css` (CSS variables for theming), `assets/presentation_template.html` (layout/tabs), or `assets/tabs/*.html` (tab content).
**⚠️ After any customization:** Always rebuild the presentation:
```bash
cd assets/
node build-presentation.js
```
**Important:** Never edit `presentation_final.html` directly — it's a generated file that gets overwritten on each build.
---
## Prerequisites
**Orchestrator**: ln-110-documents-pipeline (invokes this worker in final step)
**Standalone usage**: Can also be invoked directly for:
- Rebuilding HTML presentation after documentation updates
- Creating standalone presentation for existing docs
- Validating source documentation readiness
**Source Documentation Requirements**:
- **Required files** (must exist):
- docs/project/requirements.md
- docs/project/architecture.md
- docs/project/tech_stack.md
- **Optional files** (enhance presentation):
- docs/project/api_spec.md, database_schema.md, design_guidelines.md, runbook.md
- docs/reference/adrs/*.md (with Category field)
- docs/reference/guides/*.md
- docs/tasks/kanban_board.md
**Quality Recommendations** (warnings only, not blocking):
- architecture.md should have Mermaid diagrams (C4 Context/Container/Component)
- database_schema.md should have ER diagram
- Source docs should NOT contain placeholders (`{{PLACEHOLDER}}`, `[Add your...]`)
- Minimum content length: requirements.md >500 words, architecture.md >1000 words, tech_stack.md >200 words
**Dependencies**:
- Node.js v18+ (for build-presentation.js)
- Modern browser (Chrome/Firefox/Safari/Edge last 2 versions)
- Internet connection (Mermaid.js CDN, optional)
**Idempotent**: Yes - can be invoked multiple times without side effects:
- Preserves existing README.md
- Preserves existing assets/ (user customizations)
- Always rebuilds presentation_final.html (generated file)
---
## Definition of Done
| Phase | Critical Checkpoints |
|-------|---------------------|
| **1. READ DOCS** | ✅ All docs loaded from docs/project/, docs/reference/, docs/tasks/ ✅ Metadata extracted ✅ Mermaid blocks preserved |
| **2. VALIDATE EXISTS** | ✅ Required files exist (requirements.md, architecture.md, tech_stack.md) ✅ ERROR if missing |
| **3. VALIDATE QUALITY** | ✅ Diagrams checked ✅ Placeholders detected ✅ Content length checked ✅ WARN only (non-blocking) |
| **4. CREATE DIR** | ✅ docs/presentation/ created ✅ README.md created/preserved |
| **5. COPY TEMPLATES** | ✅ assets/ created with all templates OR preserved if exists |
| **6. INJECT CONTENT** | ✅ All 6 tabs populated ✅ **CRITICAL: Example blocks deleted** ✅ No `<!-- EXAMPLE -->` markers ✅ No hardcoded e-commerce data |
| **7. BUILD HTML** | ✅ `node build-presentation.js` executed ✅ presentation_final.html created (~120-150 KB) ✅ Tested in browser |
**Output:** docs/presentation/presentation_final.html + assets/ + README.md
---
## Example Usage
User: "Build HTML presentation"
Process:
1. **READ DOCS** - Load documentation from docs/project/, docs/reference/, docs/tasks/
2. **VALIDATE SOURCE EXISTS** - Check requirements.md, architecture.md, tech_stack.md exist (ERROR if missing)
3. **VALIDATE SOURCE QUALITY** - Check diagrams, placeholders, content length (WARN if issues, but continue)
4. **CREATE DIR** - Create docs/presentation/ + README.md navigation hub
5. **COPY TEMPLATES** - Copy HTML/CSS/JS templates to assets/ (or preserve existing)
6. **INJECT CONTENT** - Parse MD docs → replace placeholders in tabs → delete example blocks
7. **BUILD HTML** - Assemble modular components → standalone presentation_final.html (~120-150 KB)
Output: docs/presentation/presentation_final.html (6 tabs: Overview, Requirements, Architecture, Technical Spec, Roadmap, Guides) + docs/presentation/README.md (navigation hub) + docs/presentation/assets/ (modular source files)
---
## Troubleshooting
- **ERROR: Missing required files**: Run ln-114-project-docs-creator to create requirements.md, architecture.md, tech_stack.md
- **WARN: Missing diagrams**: Add Mermaid diagrams to architecture.md (C4 Context/Container/Component) and database_schema.md (ER diagram)
- **WARN: Placeholders found**: Complete documentation in source MD files before building
- **WARN: Sparse content**: Expand documentation (requirements.md >500 words, architecture.md >1000 words, tech_stack.md >200 words)
- **Build script fails**: Check Node.js v18+, navigate to assets/, verify all files exist
- **Mermaid diagrams not rendering**: Check syntax with Mermaid Live Editor, verify CDN loaded
- **Tabs not switching**: Check JavaScript loaded, open browser console for errors
- **File too large (>200 KB)**: Reduce diagrams, minify CSS/JS, remove unused rules
---
## Technical Details
**Standards**: HTML5, CSS3 (Flexbox/Grid/Variables), ES6+, WCAG 2.1 Level AA, Mobile-first responsive design, Progressive enhancement, Mermaid.js v11
**Dependencies**:
- Node.js v18+ (build script)
- Modern browser (Chrome/Firefox/Safari/Edge last 2 versions)
- Internet connection (Mermaid.js CDN, optional)
**Language**: English only (all presentation content)
---
**Version:** 7.0.0 (MAJOR: Added Phase 2/3 validation (source docs existence + content quality). Removed ln-120-docs-validator references. Renumbered phases (2-5 → 4-7). Unified READ+VALIDATE+CREATE workflow. Read-only source validation.)
**Last Updated:** 2025-11-18

102
skills/ln-115-presentation-creator/diagram.html Normal file
View File

@@ -0,0 +1,102 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>ln-115-presentation-creator - State Diagram</title>
<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
<link rel="stylesheet" href="../shared/css/diagram.css">
</head>
<body>
<div class="container">
<header>
<h1>🎨 ln-115-presentation-creator</h1>
<p class="subtitle">Interactive HTML Presentation Creator - State Diagram</p>
</header>
<div class="info-box">
<h3>📋 Workflow Overview</h3>
<ul>
<li><strong>Purpose:</strong> Build interactive HTML presentation from project documentation</li>
<li><strong>Output:</strong> Single HTML file with 6 tabs (Overview, Requirements, Architecture, Technical Spec, Roadmap, Guides)</li>
<li><strong>Technologies:</strong> Mermaid v11, table-based structure, English language</li>
<li><strong>Use after:</strong> ln-114-project-docs-creator or invoked automatically by ln-110-documents-pipeline (Phase 2.5)</li>
<li><strong>Validation:</strong> Phase 2 source docs existence + Phase 3 content quality validation (read-only)</li>
</ul>
</div>
<div class="legend">
<div class="legend-item">
<div class="legend-color color-discovery"></div>
<span>Discovery/Validation</span>
</div>
<div class="legend-item">
<div class="legend-color color-processing"></div>
<span>Content Processing</span>
</div>
<div class="legend-item">
<div class="legend-color color-action"></div>
<span>Output Generation</span>
</div>
</div>
<div class="diagram-container">
<div class="mermaid">
graph TD
Start([Start: Build HTML Presentation]) --> Phase1[Phase 1: Read Source Documents<br/>Requirements, Architecture, Tech Spec, ADRs, Guides]
Phase1 --> Phase2[Phase 2: Validate Source Exists<br/>Check required/optional files]
Phase2 --> Phase3[Phase 3: Validate Content Quality<br/>Mermaid diagrams, placeholders, min length]
Phase3 --> Phase4[Phase 4: Create Presentation Directory<br/>docs/presentation/ + README.md]
Phase4 --> Phase5[Phase 5: Copy Templates to Project<br/>12 HTML/CSS/JS template files]
Phase5 --> Phase6[Phase 6: Content Injection<br/>Build 6 tabs + parse Mermaid + cleanup examples]
Phase6 --> Phase7[Phase 7: Build Final HTML<br/>Combine tabs + CSS + JS → presentation_final.html]
Phase7 --> End([End: ✓ Interactive presentation created])
%% Styling
classDef discovery fill:#E3F2FD,stroke:#1976D2,stroke-width:2px
classDef processing fill:#FFF9C4,stroke:#F57C00,stroke-width:2px
classDef action fill:#C8E6C9,stroke:#388E3C,stroke-width:2px
class Phase1,Phase2,Phase3 discovery
class Phase4,Phase5,Phase6 processing
class Phase7 action
</div>
</div>
<div class="info-box">
<h3>🔑 Key Features</h3>
<ul>
<li><strong>6 Tabs:</strong> Overview (landing), Requirements (FRs/ADRs only; Non-Functional Requirements forbidden), Architecture (C4), Technical Spec (API/data), Roadmap (Kanban), Guides</li>
<li><strong>Diátaxis Framework:</strong> Structured documentation approach</li>
<li><strong>SCOPE Tags:</strong> Each tab has defined scope boundaries</li>
<li><strong>Template Ownership:</strong> All HTML/CSS/JS templates in references/ directory (12 files)</li>
<li><strong>Unified Workflow:</strong> READ+VALIDATE+CREATE with Phase 2/3 validation, renumbered phases (2-5 → 4-7)</li>
</ul>
</div>
<footer>
<p>Generated for ln-115-presentation-creator skill | Version 7.0.0</p>
<p>Diagram format: Mermaid.js | Last updated: 2025-11-18</p>
</footer>
</div>
<script>
mermaid.initialize({
startOnLoad: true,
theme: 'default',
flowchart: {
useMaxWidth: true,
htmlLabels: true,
curve: 'basis'
}
});
</script>
</body>
</html>

2288
skills/ln-115-presentation-creator/presentation_final.html Normal file
View File

File diff suppressed because it is too large Load Diff

302
skills/ln-115-presentation-creator/references/TEMPLATE_ARCHITECTURE.md Normal file
View File

@@ -0,0 +1,302 @@
# x-html-builder Template Architecture
This document describes the structure and content specifications for all HTML templates used by x-html-builder skill.
## File Structure
All templates are stored in `x-html-builder/references/` following the Template Ownership Principle (each skill owns its templates):
```
x-html-builder/references/
├── presentation_template.html # Base HTML5 structure with 6 tab navigation
├── styles.css # CSS Variables, responsive design (~500 lines)
├── scripts.js # Tab switching, collapsible sections, Mermaid init
├── build-presentation.js # Node.js build script for inlining
└── tabs/
├── tab_overview_template.html # Landing page
├── tab_requirements_template.html # FRs + ADRs (Non-Functional Requirements are forbidden)
├── tab_architecture_template.html # C4 diagrams
├── tab_technical_spec_template.html # API + Data + Deployment
├── tab_roadmap_template.html # Kanban-style
└── tab_guides_template.html # How-to guides
```
## Tab Content Specifications
### Tab 1: Overview (Landing Page)
**File:** `tab_overview_template.html`
**SCOPE:**
- INCLUDES: Project name, tagline, business goal, tech stack badges, role-based navigation, quick stats, recent updates
- EXCLUDES: Full requirements → Requirements tab, Detailed diagrams → Architecture tab, Full roadmap → Roadmap tab, API details → Technical Spec tab
**Content Elements:**
- **Header Intro:** Project name (h1) + tagline (minimal, no gradient background)
- **Project Summary:** Business goal in "About This Project" section (h2)
- **Role-Based Navigation:** 4 cards (Developer/Architect/Product Owner/Stakeholder) - clickable, switches to relevant tab
- **Tech Stack Badges:** Technology badges with icons and names
- **Quick Stats:** Project statistics grid (total epics, completed stories, test coverage, uptime SLA)
- **Recent Updates:** Recent project updates list
- **Quick Links:** Links to other tabs (Requirements, Architecture, API Reference, Roadmap)
**Data Sources:**
- requirements.md (project name, business goal)
- architecture.md (tech stack)
- kanban_board.md (stats, recent updates)
**Placeholders:**
- `{{PROJECT_NAME}}` - Project name from requirements.md ## Project Name
- `{{PROJECT_TAGLINE}}` - Short description from requirements.md
- `{{BUSINESS_GOAL}}` - Business goals section from requirements.md
- `{{TECH_STACK_BADGES}}` - Generated from architecture.md tech stack
- `{{QUICK_STATS}}` - Generated from kanban_board.md Epic Story Counters
- `{{RECENT_UPDATES}}` - Placeholder (currently undefined - TODO: specify data source)
### Tab 2: Requirements
**File:** `tab_requirements_template.html`
**SCOPE:**
- INCLUDES: Business goals, FRs (collapsible), ADRs (Strategic/Technical groups), constraints, success criteria
- EXCLUDES: Implementation details → Technical Spec, Diagrams → Architecture, Code → Guides, Non-Functional Requirements (explicitly banned from this tab)
**Content Elements:**
- **Business Goals:** Project objectives with key targets (h2 + list)
- **Functional Requirements:** Collapsible by domain (details/summary tags) - FR-XXX-001 format with Priority (MUST/SHOULD/COULD), Description
- **ADRs Section:** Grouped by category:
- **Strategic Decisions** (h3) - Business/architecture strategy ADRs
- **Technical Decisions** (h3) - Technology/implementation ADRs
- Each ADR in accordion (details/summary) with full content inline:
- Date | Status | Category (metadata line)
- Context (h4)
- Decision (h4)
- Rationale (h4 + list)
- Alternatives Considered (h4 + table: Alternative | Pros | Cons | Rejection Reason)
- Consequences (h4 + Positive/Negative lists)
- **Constraints:** Technology constraints
- **Success Criteria:** Measurable project success metrics
**Data Sources:**
- requirements.md (business goals, FRs, constraints, success criteria)
- adrs/*.md (all ADR files with Category field for grouping)
**Note:** Do not add Non-Functional Requirements (performance, security, scalability, etc.). If quality topics need coverage, describe them as architecture quality goals in narrative form only—never as NFR-XXX-001 style requirements.
**Placeholders:**
- None (all content directly from MD files)
### Tab 3: Architecture
**File:** `tab_architecture_template.html`
**SCOPE:**
- INCLUDES: C4 diagrams (Context/Container/Component), Deployment, Solution strategy, Quality attributes
- EXCLUDES: ADRs → Requirements, API details → Technical Spec, Code → Guides
**Content Elements:**
- **C4 Diagrams:** 4 levels in Mermaid syntax (preserved exactly as in architecture.md):
- System Context (C4 Level 1)
- Container Diagram (C4 Level 2)
- Component Diagram (C4 Level 3)
- Deployment Diagram
- **Solution Strategy:** Architecture pattern, API design approach
- **Quality Attributes:** Scalability, Security, Maintainability approaches
**Data Sources:**
- architecture.md (all content)
**Placeholders:**
- None (all content directly from architecture.md)
**EXCLUDES:**
- Tech stack table → moved to Technical Spec tab
- ADRs → moved to Requirements tab
### Tab 4: Technical Specification
**File:** `tab_technical_spec_template.html`
**SCOPE:**
- INCLUDES: Tech stack (detailed table), API endpoints, Authentication, Error codes, ER diagram, Data dictionary, Integrations, Deployment, Testing strategy (Risk-Based)
- EXCLUDES: Requirements → Requirements tab, Architecture diagrams → Architecture tab, How-to guides → Guides tab
**Content Elements:**
- **Technology Stack:** Detailed table (Category | Technology | Version | Purpose) - includes Frontend, Backend, Database, Infrastructure, DevOps categories
- **API Endpoints:** Table grouped by resource (Endpoint | Method | Description | Request | Response)
- **Authentication:** Auth mechanism description (JWT, OAuth, etc.)
- **Error Codes:** Standard error codes table (Code | Message | Description)
- **Data Model:** ER diagram in Mermaid + Data Dictionary table (Entity | Attributes | Description)
- **Third-Party Integrations:** External services table (Service | Purpose | API Documentation)
- **Deployment Infrastructure:** Infrastructure description (cloud provider, services)
- **Testing Strategy:** Risk-Based Testing approach (2-5 E2E, 3-8 Integration, 5-15 Unit tests per Story, total 10-28 max)
**Data Sources:**
- technical_specification.md (all content)
- architecture.md (tech stack section - moved here)
**Placeholders:**
- None (all content directly from MD files)
### Tab 5: Roadmap
**File:** `tab_roadmap_template.html`
**SCOPE:**
- INCLUDES: Kanban board (3 columns), Epic cards, Progress bars (%), Milestones
- EXCLUDES: Individual stories → Linear, Daily tasks → task tracker, Team assignments, Implementation details → Technical Spec
**Content Elements:**
- **Kanban Board:** 3 columns layout (Todo | In Progress | Done)
- **Epic Cards:** For each Epic from kanban_board.md:
- Epic number + title (h3)
- Description (p)
- Stories count: X/Y completed
- Target date or Completed date
- Status badge (status-todo | status-progress | status-done)
- Progress bar with % width
- **Milestones:** Quarterly milestones list with status indicators
**Data Sources:**
- kanban_board.md (Epic Story Counters table - Epic number, title, status, story counts, target dates)
- requirements.md (Epic descriptions)
- architecture.md (Epic technical context)
**Placeholders:**
- None (all content generated from kanban_board.md)
**Epic Status Mapping:**
- Todo → kanban-todo column, status-todo badge, 0% progress
- In Progress → kanban-progress column, status-progress badge, calculated % progress
- Done → kanban-done column, status-done badge, 100% progress
### Tab 6: Guides
**File:** `tab_guides_template.html`
**SCOPE:**
- INCLUDES: Getting started, How-to guides (task-oriented), Best practices, Troubleshooting, Contributing, External resources
- EXCLUDES: API reference → Technical Spec, Architecture → Architecture tab, Requirements → Requirements tab
**Content Elements:**
- **Getting Started:** Prerequisites, Installation steps (code blocks), Verification checklist
- **How-To Guides:** Task-oriented guides (How to Add Product, How to Test API, etc.) - steps in ordered lists
- **Best Practices:** Code style, Testing approach, Design patterns
- **Troubleshooting:** Common issues with solutions (h3 per issue + list)
- **Contributing Guidelines:** Fork, branch, test, submit PR workflow
- **External Resources:** Links to framework docs, third-party docs (target="_blank")
**Data Sources:**
- docs/guides/*.md (all guide files)
- README.md (getting started section)
- technical_specification.md (testing strategy)
**Placeholders:**
- None (all content directly from guide files)
## Build Process
**Script:** `build-presentation.js` (Node.js)
**Logic:**
1. Read `presentation_template.html`
2. Read all 6 tab files from `tabs/` directory
3. Inject tab content into template (replace `<!-- TAB_CONTENT_overview -->` etc.)
4. Read `styles.css` and inline into `<style>` tags
5. Read `scripts.js` and inline into `<script>` tags
6. Write `../presentation_final.html` (one level up from assets/)
**Expected Output:**
- Standalone HTML file (~120-150 KB)
- No external dependencies (except Mermaid.js CDN for diagram rendering)
- All CSS and JavaScript inlined
## Styling Specifications
**File:** `styles.css` (~500 lines)
**CSS Variables:**
```css
:root {
--primary-color: #2563eb;
--background-color: #f8fafc;
--text-color: #1e293b;
--border-color: #e2e8f0;
}
```
**Key Components:**
- **header-intro:** Minimal header (no gradient) - name + tagline
- **project-summary:** Business goal section (h2 + paragraph)
- **role-cards:** 4 clickable cards with hover effects (subtle, no transform)
- **badge:** Tech stack badges (inline-block, rounded, neutral colors)
- **epic-card:** Roadmap Epic cards with status badges and progress bars
- **progress-bar:** Horizontal bar with % fill (neutral colors, no gradient)
- **tabs:** Navigation bar with active tab indicator
- **kanban-board:** 3-column grid layout
- **Mermaid diagrams:** Responsive container with max-width
- **ADR accordion:** details/summary styling with expand indicator
- **Responsive breakpoints:** Mobile (<768px), Tablet (768-1024px), Desktop (>1024px)
**Design Principles:**
- Minimal, documentation-focused (vs marketing-style)
- Neutral color palette (blues, grays)
- No excessive gradients or transforms
- GitBook/Docusaurus aesthetic
- Progressive disclosure (collapsible sections)
- Information scent (clear navigation labels)
## Validation Checklist
Before completing build, verify:
- [ ] HTML structure valid (proper heading hierarchy h1 > h2 > h3)
- [ ] All 6 tabs present in navigation (overview, requirements, architecture, technical_spec, roadmap, guides)
- [ ] SCOPE tags present in each tab (HTML comments in first 3-5 lines)
- [ ] All placeholders replaced (no `{{PLACEHOLDER}}` remaining)
- [ ] Mermaid diagrams render correctly (valid syntax, no errors in console)
- [ ] Tab switching works (JavaScript loaded, localStorage state persistence)
- [ ] Collapsible sections functional (details/summary expand/collapse)
- [ ] Responsive design works (mobile/tablet/desktop breakpoints)
- [ ] Kanban board renders: 3 columns, Epic cards in correct columns, progress bars display %
- [ ] ADR grouping works: Strategic/Technical sections separate, accordion expands/collapses
- [ ] Role-based navigation cards clickable (switches to correct tabs)
- [ ] File size within expected range (~120-150 KB)
- [ ] Tested in browser: Double-click presentation_final.html → opens without errors
## Data Source Mapping
| Tab | Primary Source | Secondary Sources |
|-----|---------------|-------------------|
| Overview | requirements.md | architecture.md, kanban_board.md |
| Requirements | requirements.md | adrs/*.md |
| Architecture | architecture.md | - |
| Technical Spec | technical_specification.md | architecture.md (tech stack) |
| Roadmap | kanban_board.md | requirements.md, architecture.md |
| Guides | docs/guides/*.md | README.md, technical_specification.md |
## Placeholder Reference
| Placeholder | Source | Location |
|-------------|--------|----------|
| `{{PROJECT_NAME}}` | requirements.md | ## Project Name |
| `{{PROJECT_TAGLINE}}` | requirements.md | First paragraph or subtitle |
| `{{BUSINESS_GOAL}}` | requirements.md | ## Business Goals section |
| `{{TECH_STACK_BADGES}}` | architecture.md | ## Technology Stack section |
| `{{QUICK_STATS}}` | kanban_board.md | Epic Story Counters table |
| `{{RECENT_UPDATES}}` | **TODO: Undefined** | Need to specify data source |
## TODO: Undefined Placeholders
**RECENT_UPDATES:**
- **Current Status:** Placeholder exists in tab_overview_template.html but data source not specified
- **Recommendation:** Either:
1. Remove placeholder if not needed
2. Define data source (e.g., git log last 5 commits, or manual section in requirements.md)
3. Generate from kanban_board.md Epic status changes
---
**Version:** 1.0.0
**Last Updated:** 2025-01-31
**Related:** x-html-builder/SKILL.md

67
skills/ln-115-presentation-creator/references/build-presentation.js Normal file
View File

@@ -0,0 +1,67 @@
/**
* Build Script for HTML Presentation
*
* Reads modular HTML components and creates standalone presentation_final.html
* by inlining CSS, JavaScript, and all tab content.
*
* Usage: node build-presentation.js (run from assets/ directory)
* Output: ../presentation_final.html
*/
const fs = require('fs');
const path = require('path');
console.log('🔨 Building presentation...\n');
// 1. Read base template
console.log('📄 Reading presentation_template.html...');
let html = fs.readFileSync('presentation_template.html', 'utf-8');
// 2. Read and inject tab content
const tabs = ['overview', 'requirements', 'architecture', 'technical_spec', 'roadmap', 'guides'];
console.log('📑 Injecting tab content...');
tabs.forEach(tab => {
const tabFile = path.join('tabs', `tab_${tab}.html`);
if (fs.existsSync(tabFile)) {
const tabContent = fs.readFileSync(tabFile, 'utf-8');
const placeholder = `<!--TAB_${tab.toUpperCase()}-->`;
html = html.replace(placeholder, tabContent);
console.log(` ✓ ${tab}`);
} else {
console.log(` ⚠ ${tab} (file not found, skipping)`);
}
});
// 3. Inline CSS
console.log('🎨 Inlining styles.css...');
if (fs.existsSync('styles.css')) {
const css = fs.readFileSync('styles.css', 'utf-8');
html = html.replace('<!--STYLES-->', `<style>\n${css}\n</style>`);
console.log(' ✓ CSS inlined');
} else {
console.log(' ⚠ styles.css not found');
}
// 4. Inline JavaScript
console.log('⚡ Inlining scripts.js...');
if (fs.existsSync('scripts.js')) {
const js = fs.readFileSync('scripts.js', 'utf-8');
html = html.replace('<!--SCRIPTS-->', `<script>\n${js}\n</script>`);
console.log(' ✓ JS inlined');
} else {
console.log(' ⚠ scripts.js not found');
}
// 5. Write final presentation
const outputPath = path.join('..', 'presentation_final.html');
console.log(`\n📦 Writing ${outputPath}...`);
fs.writeFileSync(outputPath, html, 'utf-8');
// 6. Calculate file size
const stats = fs.statSync(outputPath);
const sizeKB = (stats.size / 1024).toFixed(2);
console.log(` ✓ File size: ${sizeKB} KB`);
console.log('\n✅ Build complete!');
console.log(` Open: ${outputPath}`);

389
skills/ln-115-presentation-creator/references/mermaid_guidelines.md Normal file
View File

@@ -0,0 +1,389 @@
# Mermaid.js Guidelines for x-html-builder
This guide provides best practices for working with Mermaid.js diagrams in HTML presentations with tab-based navigation.
## Version and CDN
**Current Version:** Mermaid v11.12.1 (latest stable as of 2025)
**Recommended CDN:**
```html
<!-- Standard version -->
<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
<!-- ESM version (modern browsers) -->
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
</script>
```
**Why v11?**
- Latest features and bug fixes
- Improved performance
- Better error handling
- `mermaid.init()` deprecated (use `mermaid.run()` instead)
---
## Initialization for Tab-Based Presentations
**Critical Setting:** `startOnLoad: false`
**Why?**
- Tabs with `display: none` prevent diagrams from rendering correctly
- Diagrams need manual rendering when tab becomes visible
- Allows precise control over rendering timing
**Configuration:**
```javascript
mermaid.initialize({
startOnLoad: false, // Manual control for tab switching
theme: 'default', // or 'dark', 'forest', 'neutral'
securityLevel: 'loose', // For trusted content (allows HTML labels)
logLevel: 1, // 0=none, 1=error, 2=warn, 3=info
flowchart: {
useMaxWidth: true, // Responsive diagrams
htmlLabels: true // Rich text support
}
});
```
---
## Rendering Strategies
### Strategy 1: Render Once Per Tab (Recommended)
**Best for:** Static content with tab navigation
```javascript
document.addEventListener('DOMContentLoaded', async function() {
// Initialize Mermaid
mermaid.initialize({ startOnLoad: false });
// Render initially active tab
const activeTab = document.querySelector('.tab-content.active');
if (activeTab && !activeTab.dataset.mermaidRendered) {
await mermaid.run({
nodes: activeTab.querySelectorAll('.mermaid'),
suppressErrors: true
});
activeTab.dataset.mermaidRendered = 'true'; // Mark as rendered
}
});
async function switchTab(tabName) {
// ... tab switching logic ...
// Render diagrams only if not already rendered
const activeTab = document.getElementById(`${tabName}-tab`);
if (activeTab && !activeTab.dataset.mermaidRendered) {
await mermaid.run({
nodes: activeTab.querySelectorAll('.mermaid'),
suppressErrors: true
});
activeTab.dataset.mermaidRendered = 'true';
}
}
```
**Benefits:**
- ✅ Performance: Each tab rendered only once
- ✅ No duplicate diagrams
- ✅ Minimal re-rendering overhead
### Strategy 2: Render All on Load
**Best for:** Small number of tabs (<5), simple diagrams
```javascript
document.addEventListener('DOMContentLoaded', async function() {
mermaid.initialize({ startOnLoad: false });
// Render ALL diagrams at once
await mermaid.run({
querySelector: '.mermaid',
suppressErrors: true
});
});
```
**Benefits:**
- ✅ Simple implementation
- ✅ No tab-switch delays
- ❌ Slower initial load for many diagrams
### Strategy 3: Manual Rendering API
**Best for:** Dynamic content from API, programmatic diagram generation
```javascript
const graphDefinition = `
graph TD
A[Client] --> B[Load Balancer]
B --> C[Server1]
B --> D[Server2]
`;
const { svg } = await mermaid.render('uniqueId', graphDefinition);
document.getElementById('diagram-container').innerHTML = svg;
```
**Benefits:**
- ✅ Full control over rendering
- ✅ Can modify SVG before insertion
- ✅ Works with dynamic content
---
## Common Errors and Solutions
| Error | Cause | Solution |
|-------|-------|----------|
| **Diagrams not rendering in hidden tabs** | `startOnLoad: true` + `display: none` | Use `startOnLoad: false` + `mermaid.run()` on tab switch |
| **Duplicate diagrams** | Re-rendering already rendered content | Cache rendered tabs with `data-mermaid-rendered` attribute |
| **"mermaid.init is deprecated"** | Using old API | Replace `mermaid.init()` with `mermaid.run()` |
| **SVG sizing issues** | Rendering while element is hidden | Add `setTimeout(... , 50)` before rendering to ensure tab is visible |
| **Parsing errors break page** | Invalid Mermaid syntax | Use `suppressErrors: true` in `mermaid.run()` |
| **Fonts not loaded** | Rendering before fonts ready | Wait for `DOMContentLoaded` + small delay (50-100ms) |
| **Different themes on tabs** | Theme not applied to new renders | Re-initialize theme before rendering: `mermaid.initialize({ theme: 'dark' })` |
---
## Performance Optimization
### 1. Lazy Rendering
Only render diagrams when tab becomes visible (Strategy 1).
### 2. Caching
Use `data-mermaid-rendered` attribute to avoid re-rendering:
```javascript
if (!element.dataset.mermaidRendered) {
await mermaid.run({ nodes: [element] });
element.dataset.mermaidRendered = 'true';
}
```
### 3. Batch Rendering
Render multiple diagrams in one `mermaid.run()` call:
```javascript
// Good: One call for all diagrams in tab
await mermaid.run({ nodes: tab.querySelectorAll('.mermaid') });
// Bad: Multiple calls
diagrams.forEach(d => mermaid.run({ nodes: [d] }));
```
### 4. Error Suppression (Production)
Prevent parsing errors from breaking the page:
```javascript
await mermaid.run({ suppressErrors: true });
```
### 5. Async/Await
Always use async/await for predictable rendering:
```javascript
async function renderDiagrams() {
await mermaid.run({ ... }); // Wait for completion
console.log('Rendering complete');
}
```
---
## Security Levels
**Choose based on content trust level:**
### `loose` (Recommended for Documentation)
```javascript
mermaid.initialize({ securityLevel: 'loose' });
```
- Allows HTML labels
- Allows some scripts in labels
- **Use for:** Internal docs, trusted content
### `strict` (User-Generated Content)
```javascript
mermaid.initialize({ securityLevel: 'strict' });
```
- Blocks all scripts
- Sanitizes HTML
- **Use for:** User-submitted diagrams, public content
### `antiscript` (Middle Ground)
```javascript
mermaid.initialize({ securityLevel: 'antiscript' });
```
- Removes scripts from output
- Allows safe HTML
---
## Code Examples
### Complete Tab-Based Implementation
```javascript
document.addEventListener('DOMContentLoaded', async function() {
// Initialize Mermaid
if (typeof mermaid !== 'undefined') {
mermaid.initialize({
startOnLoad: false,
theme: 'default',
securityLevel: 'loose',
logLevel: 1,
flowchart: {
useMaxWidth: true,
htmlLabels: true
}
});
// Render initially active tab
setTimeout(async () => {
const activeTab = document.querySelector('.tab-content.active');
if (activeTab && !activeTab.dataset.mermaidRendered) {
try {
await mermaid.run({
nodes: activeTab.querySelectorAll('.mermaid'),
suppressErrors: true
});
activeTab.dataset.mermaidRendered = 'true';
} catch (err) {
console.error('Mermaid rendering error:', err);
}
}
}, 100);
}
// Tab switching
async function switchTab(tabName) {
// ... tab activation logic ...
// Render diagrams if not already rendered
if (typeof mermaid !== 'undefined') {
const activeTab = document.getElementById(`${tabName}-tab`);
if (activeTab && !activeTab.dataset.mermaidRendered) {
setTimeout(async () => {
try {
await mermaid.run({
nodes: activeTab.querySelectorAll('.mermaid'),
suppressErrors: true
});
activeTab.dataset.mermaidRendered = 'true';
} catch (err) {
console.error('Mermaid rendering error on tab switch:', err);
}
}, 50);
}
}
}
});
```
### Error Handling with Fallback
```javascript
async function renderMermaidSafe(element) {
try {
await mermaid.run({ nodes: [element] });
} catch (err) {
console.error('Mermaid error:', err);
element.innerHTML = `
<div style="color: red; padding: 10px; border: 1px solid red;">
⚠️ Diagram rendering failed. Check syntax.
</div>
`;
}
}
```
---
## Migration Notes: v10 → v11
**Breaking Changes:**
- ❌ `mermaid.init()` is deprecated → Use `mermaid.run()`
- ⚠️ Some theme options renamed (check docs)
**Recommended Changes:**
```javascript
// Old (v10)
mermaid.init(undefined, '.mermaid');
// New (v11)
await mermaid.run({ querySelector: '.mermaid' });
```
**CDN Update:**
```html
<!-- v10 -->
<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
<!-- v11 -->
<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
```
**Compatibility:**
- ✅ All diagram types (flowchart, sequence, class, ER, etc.) work in v11
- ✅ Themes are compatible
- ✅ Configuration options mostly unchanged
---
## Troubleshooting Checklist
When diagrams don't render:
1. **Check CDN loading:**
```javascript
console.log(typeof mermaid); // Should be 'object', not 'undefined'
```
2. **Check initialization:**
```javascript
console.log(mermaid.initialize); // Should be a function
```
3. **Check element visibility:**
```javascript
const el = document.querySelector('.mermaid');
console.log(window.getComputedStyle(el).display); // Should NOT be 'none'
```
4. **Check for syntax errors:**
- Open browser console
- Look for Mermaid parsing errors
- Validate syntax at https://mermaid.live
5. **Check timing:**
- Are you rendering before DOM is ready?
- Is element visible when rendering?
- Try adding `setTimeout(... , 100)` delay
---
## Best Practices Summary
✅ **DO:**
- Use `startOnLoad: false` for tab-based layouts
- Cache rendered tabs with `data-mermaid-rendered`
- Use async/await for predictable rendering
- Add error handling with `suppressErrors: true`
- Wait for element visibility before rendering
- Use `mermaid.run()` (not deprecated `init()`)
❌ **DON'T:**
- Use `startOnLoad: true` with hidden tabs
- Re-render already rendered diagrams
- Render while element has `display: none`
- Use `mermaid.init()` (deprecated)
- Ignore parsing errors in production
- Mix rendering strategies
---
**Version:** 1.0.0
**Last Updated:** 2025-11-06
**Mermaid Version:** v11.12.1
**Compatible with:** x-html-builder v2.3.1+

146
skills/ln-115-presentation-creator/references/presentation_readme_template.md Normal file
View File

@@ -0,0 +1,146 @@
# {{PROJECT_NAME}} - Presentation
> **SCOPE:** Navigation hub for project presentation (HTML presentation access, customization guide, build instructions ONLY). DO NOT add here: Project documentation → docs/project/, Architecture details → docs/project/architecture.md, Technical specs → docs/project/tech_stack.md
---
## Purpose
This directory contains the interactive HTML presentation for **{{PROJECT_NAME}}**, generated from project documentation (requirements, architecture, technical specifications).
**Use this when:**
- Presenting project overview to stakeholders
- Onboarding new team members
- Sharing project architecture visually
- Creating project demos
---
## Quick Navigation
**Main Presentation:**
- [presentation_final.html](presentation_final.html) - Open this in your browser
**Modular Structure:**
- [assets/presentation_template.html](assets/presentation_template.html) - Base template
- [assets/styles.css](assets/styles.css) - Styling
- [assets/scripts.js](assets/scripts.js) - Tab switching logic
- [assets/tabs/](assets/tabs/) - Individual tab content (tab_overview.html, tab_requirements.html, tab_architecture.html, tab_technical_spec.html, tab_roadmap.html, tab_guides.html)
- [assets/build-presentation.js](assets/build-presentation.js) - Build script
**⚠️ IMPORTANT: presentation_final.html is a GENERATED file**
- DO NOT edit presentation_final.html directly - changes will be overwritten on next build
- ALL changes must be made in source files (tabs/*.html, styles.css, scripts.js, presentation_template.html)
- Rebuild after source changes: `node docs/presentation/assets/build-presentation.js`
---
## Customization Guide
### Editing Content
1. **Edit individual tabs** in `assets/tabs/`:
- `tab_overview.html` - Project overview and key information
- `tab_requirements.html` - Functional requirements and acceptance criteria
- `tab_architecture.html` - System architecture and C4 diagrams
- `tab_technical_spec.html` - Technology stack, API, database (or specialized tabs)
- `tab_roadmap.html` - Project roadmap and milestones
- `tab_guides.html` - Quick guides and best practices
2. **Update styles** in `assets/css/custom.css`:
- Modify colors, fonts, spacing
- Customize section backgrounds
- Adjust diagram styles
3. **Modify behavior** in `assets/js/custom.js`:
- Add custom interactions
- Implement navigation helpers
- Integrate analytics
### Presentation Update Workflow
**⚠️ CRITICAL RULE: NEVER edit presentation_final.html directly (it's a generated file)**
Follow this workflow for ALL presentation updates:
1. **Identify what to change:**
- Content update → Edit `assets/tabs/tab_*.html` (6 files)
- Styling update → Edit `assets/styles.css`
- Behavior update → Edit `assets/scripts.js`
- Layout update → Edit `assets/presentation_template.html`
2. **Make changes ONLY in source files:**
- Tab content: `assets/tabs/tab_overview.html`, `tab_requirements.html`, `tab_architecture.html`, `tab_technical_spec.html`, `tab_roadmap.html`, `tab_guides.html`
- Styling: `assets/styles.css`
- JavaScript: `assets/scripts.js`
- Template: `assets/presentation_template.html`
3. **Rebuild presentation:**
```bash
cd docs/presentation
node assets/build-presentation.js
```
4. **Verify changes:**
- Open `presentation_final.html` in browser
- Check all tabs load correctly
- Verify diagrams render properly
- Test navigation between tabs
5. **Commit BOTH:**
- Source files (assets/tabs/, assets/*.{css,js,html})
- Regenerated `presentation_final.html`
**Why this matters:** presentation_final.html is auto-generated by combining all source files. Direct edits will be lost on next rebuild.
---
## Build Instructions
**Prerequisites:**
- Project documentation in `docs/project/` (requirements.md, architecture.md, tech_stack.md, etc.)
**Build Process:**
1. Run skill: `ln-115-presentation-creator`
2. Skill reads documentation from `docs/project/`
3. Generates HTML tabs in `assets/tabs/`
4. Combines tabs into `presentation_final.html`
5. Creates this README for navigation
**Rebuild Triggers:**
- Updated project documentation
- New architecture diagrams
- Changed requirements or roadmap
- Added new guides
---
## Maintenance
**Last Updated:** {{LAST_UPDATED}}
**Update Triggers:**
- Documentation updates in docs/project/
- New C4 diagrams or Mermaid charts
- Roadmap or milestone changes
- Design system updates
**Verification:**
- [ ] presentation_final.html opens without errors
- [ ] All tabs load correctly (Overview, Requirements, Architecture, etc.)
- [ ] Mermaid diagrams render properly
- [ ] Navigation between tabs works
- [ ] All links to documentation are valid
---
## Related Documentation
- [Project Documentation](../project/README.md) - Source for presentation content
- [Architecture Diagrams](../project/architecture.md) - C4 Model diagrams
- [Requirements](../project/requirements.md) - Functional requirements
---
**Template Version:** 1.0.0
**Last Updated:** {{LAST_UPDATED}}

66
skills/ln-115-presentation-creator/references/presentation_template.html Normal file
View File

@@ -0,0 +1,66 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>E-Commerce Platform - Documentation</title>
<!-- Mermaid.js for diagrams (v11) -->
<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
<!--STYLES-->
</head>
<body>
<div class="container">
<!-- Header -->
<header class="header">
<h1>E-Commerce Platform</h1>
<p class="subtitle">Modern Online Shopping Solution</p>
</header>
<!-- Tab Navigation -->
<nav class="tabs">
<button class="tab-button active" data-tab="overview">Overview</button>
<button class="tab-button" data-tab="requirements">Requirements</button>
<button class="tab-button" data-tab="architecture">Architecture</button>
<button class="tab-button" data-tab="technical_spec">Technical Spec</button>
<button class="tab-button" data-tab="roadmap">Roadmap</button>
<button class="tab-button" data-tab="guides">Guides</button>
</nav>
<!-- Tab Content -->
<main class="content">
<div id="overview-tab" class="tab-content active">
<!--TAB_OVERVIEW-->
</div>
<div id="requirements-tab" class="tab-content">
<!--TAB_REQUIREMENTS-->
</div>
<div id="architecture-tab" class="tab-content">
<!--TAB_ARCHITECTURE-->
</div>
<div id="technical_spec-tab" class="tab-content">
<!--TAB_TECHNICAL_SPEC-->
</div>
<div id="roadmap-tab" class="tab-content">
<!--TAB_ROADMAP-->
</div>
<div id="guides-tab" class="tab-content">
<!--TAB_GUIDES-->
</div>
</main>
<!-- Footer -->
<footer class="footer">
<p>Generated on 2025-11-05 | Powered by <a href="https://github.com/anthropics/claude-code" target="_blank">Claude Code</a></p>
</footer>
</div>
<!--SCRIPTS-->
</body>
</html>

124
skills/ln-115-presentation-creator/references/scripts.js Normal file
View File

@@ -0,0 +1,124 @@
/**
* Presentation Scripts
*
* Features:
* - Tab switching with state persistence (localStorage)
* - Collapsible sections
* - Mermaid diagram initialization
* - Smooth scrolling
*/
document.addEventListener('DOMContentLoaded', async function() {
// Initialize Mermaid with manual control for tab switching
if (typeof mermaid !== 'undefined') {
mermaid.initialize({
startOnLoad: false, // Manual control for better tab switching
theme: 'default',
securityLevel: 'loose',
logLevel: 1, // Only show errors
flowchart: {
useMaxWidth: true,
htmlLabels: true
}
});
// Render diagrams in the initially active tab (only once)
setTimeout(async () => {
const activeTab = document.querySelector('.tab-content.active');
if (activeTab && !activeTab.dataset.mermaidRendered) {
try {
await mermaid.run({
nodes: activeTab.querySelectorAll('.mermaid'),
suppressErrors: true
});
activeTab.dataset.mermaidRendered = 'true';
} catch (err) {
console.error('Mermaid rendering error:', err);
}
}
}, 100);
}
// Tab Switching
const tabButtons = document.querySelectorAll('.tab-button');
const tabPanes = document.querySelectorAll('.tab-content');
// Load saved tab from localStorage
const savedTab = localStorage.getItem('activeTab') || 'overview';
switchTab(savedTab);
tabButtons.forEach(button => {
button.addEventListener('click', function() {
const tabName = this.getAttribute('data-tab');
switchTab(tabName);
});
});
async function switchTab(tabName) {
// Update buttons
tabButtons.forEach(btn => {
btn.classList.remove('active');
if (btn.getAttribute('data-tab') === tabName) {
btn.classList.add('active');
}
});
// Update panes
tabPanes.forEach(pane => {
pane.classList.remove('active');
if (pane.id === `${tabName}-tab`) {
pane.classList.add('active');
}
});
// Save to localStorage
localStorage.setItem('activeTab', tabName);
// Render Mermaid diagrams in newly activated tab (only once per tab)
if (typeof mermaid !== 'undefined') {
const activeTab = document.getElementById(`${tabName}-tab`);
if (activeTab && !activeTab.dataset.mermaidRendered) {
setTimeout(async () => {
try {
await mermaid.run({
nodes: activeTab.querySelectorAll('.mermaid'),
suppressErrors: true
});
activeTab.dataset.mermaidRendered = 'true';
} catch (err) {
console.error('Mermaid rendering error on tab switch:', err);
}
}, 50);
}
}
// Scroll to top
window.scrollTo({ top: 0, behavior: 'smooth' });
}
// Make switchTab available globally for inline onclick handlers
window.switchTab = switchTab;
// Search functionality
const searchInput = document.getElementById('search');
if (searchInput) {
searchInput.addEventListener('input', function() {
const query = this.value.toLowerCase();
// Basic search implementation - can be enhanced
if (query.length > 2) {
console.log('Searching for:', query);
// TODO: Implement search across all tabs
}
});
}
// Collapsible sections (details/summary elements)
document.querySelectorAll('details').forEach(detail => {
detail.addEventListener('toggle', function() {
if (this.open) {
// Scroll into view when expanded
this.scrollIntoView({ behavior: 'smooth', block: 'nearest' });
}
});
});
});

778
skills/ln-115-presentation-creator/references/styles.css Normal file
View File

@@ -0,0 +1,778 @@
/* ==================== CSS Variables ==================== */
:root {
--primary-color: #2563eb;
--secondary-color: #1e40af;
--success-color: #10b981;
--warning-color: #f59e0b;
--danger-color: #ef4444;
--text-color: #1f2937;
--text-light: #6b7280;
--bg-color: #ffffff;
--bg-light: #f9fafb;
--bg-dark: #f3f4f6;
--border-color: #e5e7eb;
--code-bg: #f3f4f6;
--shadow: 0 1px 3px 0 rgba(0, 0, 0, 0.1);
--shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1);
}
/* ==================== Global Styles ==================== */
* {
margin: 0;
padding: 0;
box-sizing: border-box;
}
body {
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
line-height: 1.6;
color: var(--text-color);
background-color: var(--bg-light);
}
/* ==================== Container ==================== */
.container {
max-width: 1200px;
margin: 0 auto;
padding: 20px;
}
/* ==================== Header ==================== */
.header {
text-align: center;
padding: 40px 20px;
background: linear-gradient(135deg, var(--primary-color), var(--secondary-color));
color: white;
border-radius: 8px;
margin-bottom: 30px;
box-shadow: var(--shadow-lg);
}
.header h1 {
font-size: 2.5rem;
margin-bottom: 10px;
text-shadow: 0 2px 4px rgba(0, 0, 0, 0.3);
font-weight: 700;
}
.subtitle {
font-size: 1.1rem;
opacity: 0.95;
text-shadow: 0 1px 2px rgba(0, 0, 0, 0.2);
}
/* ==================== Tabs Navigation ==================== */
.tabs {
display: flex;
gap: 5px;
margin-bottom: 20px;
flex-wrap: wrap;
}
.tab-button {
flex: 1;
min-width: 120px;
padding: 12px 20px;
background-color: var(--bg-color);
border: 2px solid var(--border-color);
border-radius: 8px 8px 0 0;
cursor: pointer;
font-size: 1rem;
font-weight: 500;
color: var(--text-color);
transition: all 0.3s ease;
}
.tab-button:hover {
background-color: var(--bg-dark);
border-color: var(--primary-color);
}
.tab-button.active {
background-color: var(--primary-color);
color: white;
border-color: var(--primary-color);
}
/* ==================== Tab Content ==================== */
.content {
background-color: var(--bg-color);
border-radius: 8px;
padding: 40px;
box-shadow: var(--shadow);
min-height: 500px;
}
.tab-content {
display: none;
}
.tab-content.active {
display: block;
animation: fadeIn 0.3s ease;
}
@keyframes fadeIn {
from { opacity: 0; transform: translateY(10px); }
to { opacity: 1; transform: translateY(0); }
}
/* ==================== Typography ==================== */
h1 {
font-size: 2rem;
color: var(--primary-color);
margin-bottom: 20px;
}
h2 {
font-size: 1.75rem;
color: var(--primary-color);
margin-bottom: 20px;
padding-bottom: 10px;
border-bottom: 3px solid var(--primary-color);
}
h3 {
font-size: 1.5rem;
color: var(--secondary-color);
margin-top: 30px;
margin-bottom: 15px;
}
h4 {
font-size: 1.2rem;
color: var(--text-color);
margin-top: 20px;
margin-bottom: 10px;
}
p {
margin-bottom: 15px;
line-height: 1.8;
}
ul, ol {
margin-left: 30px;
margin-bottom: 15px;
}
li {
margin-bottom: 8px;
}
section {
margin-bottom: 40px;
}
/* ==================== Code Blocks ==================== */
code {
background-color: var(--code-bg);
padding: 2px 6px;
border-radius: 4px;
font-family: "Monaco", "Courier New", monospace;
font-size: 0.9em;
color: var(--danger-color);
}
pre {
background-color: var(--code-bg);
padding: 15px;
border-radius: 8px;
overflow-x: auto;
margin-bottom: 20px;
border-left: 4px solid var(--primary-color);
}
pre code {
background-color: transparent;
padding: 0;
color: var(--text-color);
}
/* ==================== Tables ==================== */
table {
width: 100%;
border-collapse: collapse;
margin-bottom: 20px;
box-shadow: var(--shadow);
}
thead {
background-color: var(--primary-color);
color: white;
}
th, td {
padding: 12px;
text-align: left;
border-bottom: 1px solid var(--border-color);
}
tbody tr:hover {
background-color: var(--bg-light);
}
/* ==================== Cards ==================== */
.card {
background-color: var(--bg-light);
border-radius: 8px;
padding: 20px;
margin-bottom: 20px;
box-shadow: var(--shadow);
border-left: 4px solid var(--primary-color);
}
.card h4 {
margin-top: 0;
color: var(--primary-color);
}
/* ==================== Badges ==================== */
.badge {
display: inline-block;
padding: 4px 10px;
border-radius: 12px;
font-size: 0.85rem;
font-weight: 600;
margin-right: 5px;
}
.badge-success {
background-color: var(--success-color);
color: white;
}
.badge-warning {
background-color: var(--warning-color);
color: white;
}
.badge-danger {
background-color: var(--danger-color);
color: white;
}
.badge-primary {
background-color: var(--primary-color);
color: white;
}
/* ==================== Overview Tab Components ==================== */
/* Role-based Navigation Cards */
.role-navigation {
margin: 40px 0;
}
.role-cards {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
gap: 20px;
margin-top: 20px;
}
.role-card {
padding: 20px;
background-color: var(--bg-color);
border: 2px solid var(--border-color);
border-radius: 8px;
cursor: pointer;
transition: all 0.3s ease;
box-shadow: var(--shadow);
}
.role-card:hover {
border-color: var(--primary-color);
box-shadow: var(--shadow-lg);
transform: translateY(-2px);
}
.role-card h3 {
font-size: 1.1rem;
margin-top: 0;
margin-bottom: 10px;
color: var(--text-color);
}
.role-card p {
font-size: 0.9rem;
color: var(--text-light);
margin: 0;
}
/* Tech Stack Badges */
.tech-stack-section {
margin: 40px 0;
}
.tech-badges {
display: flex;
flex-wrap: wrap;
gap: 12px;
margin-top: 15px;
}
.tech-badge {
padding: 8px 16px;
background-color: var(--bg-light);
border: 1px solid var(--border-color);
border-radius: 6px;
font-size: 0.9rem;
font-weight: 500;
color: var(--text-color);
}
/* Quick Stats */
.quick-stats {
margin: 40px 0;
}
.stats-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
gap: 20px;
margin-top: 20px;
}
.stat-card {
padding: 20px;
background-color: var(--bg-light);
border-radius: 8px;
text-align: center;
box-shadow: var(--shadow);
}
.stat-card h3 {
font-size: 2rem;
color: var(--primary-color);
margin: 0 0 5px 0;
}
.stat-card p {
font-size: 0.9rem;
color: var(--text-light);
margin: 0;
}
/* Quick Links */
/* ==================== Overview Tab - New Components ==================== */
/* Stakeholders Section */
.stakeholders-section {
margin: 40px 0;
}
.stakeholders-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
gap: 20px;
margin-top: 20px;
}
.stakeholder-card {
padding: 20px;
background-color: var(--bg-light);
border-radius: 8px;
text-align: center;
box-shadow: var(--shadow);
border-top: 4px solid var(--primary-color);
}
.stakeholder-card h3 {
font-size: 1rem;
color: var(--text-color);
margin: 0 0 8px 0;
}
.stakeholder-card p {
font-size: 0.9rem;
margin: 3px 0;
}
.stakeholder-card .role {
color: var(--text-light);
font-size: 0.85rem;
}
/* Navigation Guide */
.navigation-guide {
margin: 40px 0;
}
.guide-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
gap: 20px;
margin-top: 20px;
}
.guide-card {
padding: 20px;
background-color: var(--bg-light);
border: 2px solid var(--border-color);
border-radius: 8px;
transition: all 0.3s ease;
}
.guide-card:hover {
border-color: var(--primary-color);
box-shadow: var(--shadow-lg);
transform: translateY(-2px);
}
.guide-card h3 {
font-size: 1.1rem;
color: var(--primary-color);
margin: 0 0 10px 0;
}
.guide-card p {
font-size: 0.9rem;
color: var(--text-color);
margin: 8px 0;
}
.guide-card .audience {
font-size: 0.85rem;
color: var(--text-light);
font-style: italic;
margin-top: 12px;
}
/* ==================== Roadmap Tab Components ==================== */
/* Roadmap Intro */
.roadmap-intro {
background-color: var(--bg-light);
padding: 20px;
border-radius: 8px;
border-left: 4px solid var(--primary-color);
margin-bottom: 30px;
font-size: 1rem;
line-height: 1.6;
}
/* Kanban Board - 5 columns layout */
/* ==================== Epics List (Roadmap) ==================== */
.epics-list {
display: flex;
flex-direction: column;
gap: 24px;
margin: 30px 0;
}
.epic-item {
background-color: var(--bg-color);
border: 1px solid var(--border-color);
border-radius: 8px;
padding: 24px;
box-shadow: var(--shadow);
transition: box-shadow 0.3s ease;
}
.epic-item:hover {
box-shadow: var(--shadow-lg);
}
.epic-header {
display: flex;
justify-content: space-between;
align-items: center;
margin-bottom: 12px;
}
.epic-header h3 {
margin: 0;
font-size: 1.4rem;
color: var(--text-color);
}
.epic-description {
color: var(--text-light);
margin-bottom: 16px;
font-size: 1rem;
}
.epic-details {
display: grid;
grid-template-columns: 1fr 1fr;
gap: 20px;
margin-bottom: 16px;
padding: 16px;
background-color: var(--bg-light);
border-radius: 6px;
}
.epic-scope h4 {
font-size: 0.9rem;
text-transform: uppercase;
color: var(--text-light);
margin-bottom: 8px;
font-weight: 600;
}
.epic-scope ul {
margin: 0;
padding-left: 20px;
}
.epic-scope li {
font-size: 0.9rem;
margin-bottom: 4px;
}
.epic-meta {
border-top: 1px solid var(--border-color);
padding-top: 12px;
margin-top: 12px;
}
.epic-meta p {
margin: 4px 0;
font-size: 0.9rem;
color: var(--text-light);
}
/* Epic Status Badges */
.epic-status {
padding: 6px 12px;
border-radius: 12px;
font-size: 0.85rem;
font-weight: 600;
text-transform: uppercase;
}
.status-done {
background-color: #d1fae5;
color: #065f46;
}
.status-progress {
background-color: #dbeafe;
color: #1e40af;
}
.status-todo {
background-color: #f3f4f6;
color: #4b5563;
}
.status-backlog {
background-color: #fef3c7;
color: #92400e;
}
/* Out of Scope Items */
.out-of-scope-items {
margin: 40px 0;
}
.out-of-scope-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
gap: 20px;
margin-top: 20px;
}
.out-of-scope-card {
background-color: #fef2f2;
border: 2px solid #fca5a5;
border-radius: 8px;
padding: 16px;
}
.out-of-scope-card h4 {
color: #dc2626;
margin: 0 0 8px 0;
}
.scope-reason {
font-size: 0.85rem;
color: var(--text-light);
margin-top: 8px;
font-style: italic;
}
/* Roadmap Legend */
.roadmap-legend {
margin-top: 32px;
padding: 16px;
background-color: var(--bg-light);
border-radius: 8px;
}
.status-badges {
display: flex;
gap: 12px;
flex-wrap: wrap;
align-items: center;
font-size: 0.9rem;
margin-top: 12px;
}
.progress-fill {
background: linear-gradient(90deg, var(--primary-color), var(--secondary-color));
height: 100%;
border-radius: 4px;
transition: width 0.5s ease;
}
/* Roadmap Legend */
.roadmap-legend {
margin: 40px 0;
background-color: var(--bg-light);
padding: 20px;
border-radius: 8px;
border: 1px solid var(--border-color);
}
.roadmap-legend h3 {
margin-top: 0;
color: var(--primary-color);
}
.roadmap-legend ul {
margin-left: 20px;
}
.roadmap-legend li {
margin-bottom: 10px;
}
/* ==================== Requirements Tab Components ==================== */
/* Priority Badges */
.priority-must {
background-color: #fee2e2;
color: #991b1b;
padding: 4px 8px;
border-radius: 4px;
font-size: 0.75rem;
font-weight: 700;
text-transform: uppercase;
}
/* ADR Accordion */
.adr-section {
margin: 40px 0;
}
.adr-group {
margin: 30px 0;
}
.adr-group h3 {
margin-top: 40px;
margin-bottom: 20px;
}
details.adr-item {
margin-bottom: 15px;
padding: 15px;
background-color: var(--bg-light);
border: 1px solid var(--border-color);
border-radius: 8px;
}
details.adr-item summary {
cursor: pointer;
font-weight: 600;
color: var(--primary-color);
font-size: 1.1rem;
}
details.adr-item summary:hover {
color: var(--secondary-color);
}
details.adr-item[open] summary {
margin-bottom: 15px;
padding-bottom: 15px;
border-bottom: 2px solid var(--border-color);
}
/* Collapsible Sections */
details {
margin-bottom: 15px;
}
summary {
cursor: pointer;
font-weight: 600;
padding: 10px;
background-color: var(--bg-light);
border-radius: 4px;
}
summary:hover {
background-color: var(--bg-dark);
}
/* ==================== Mermaid Diagrams ==================== */
.mermaid {
background-color: white;
padding: 20px;
border-radius: 8px;
margin: 20px 0;
text-align: center;
border: 1px solid var(--border-color);
}
/* ==================== Blockquotes ==================== */
blockquote {
margin: 20px 0;
padding: 15px 20px;
border-left: 4px solid var(--primary-color);
background-color: var(--bg-light);
font-style: italic;
color: var(--text-light);
}
/* ==================== Footer ==================== */
.footer {
text-align: center;
padding: 20px;
margin-top: 40px;
color: var(--text-light);
font-size: 0.9rem;
border-top: 2px solid var(--border-color);
}
/* ==================== Responsive Design ==================== */
@media (max-width: 768px) {
.header h1 {
font-size: 1.8rem;
}
.tabs {
flex-direction: column;
}
.tab-button {
width: 100%;
}
.content {
padding: 20px;
}
.epic-details {
grid-template-columns: 1fr;
}
.out-of-scope-grid {
grid-template-columns: 1fr;
}
.role-cards {
grid-template-columns: 1fr;
}
.stats-grid {
grid-template-columns: 1fr;
}
table {
font-size: 0.9rem;
}
th, td {
padding: 8px;
}
}

177
skills/ln-115-presentation-creator/references/tabs/tab_architecture.html Normal file
View File

@@ -0,0 +1,177 @@
<!-- SCOPE: System Structure Visualization (Diagrams Only) -->
<!-- INCLUDES: C4 diagrams (Context/Container/Component), Deployment diagram, brief captions -->
<!-- EXCLUDES: Decision rationale → ADRs, Requirements → Requirements tab, API details → Technical Spec, Non-Functional Requirements (forbidden; keep quality topics as architecture narrative only) -->
<h2>Architecture</h2>
<!-- PLACEHOLDER: {{C4_CONTEXT}} -->
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
<section class="c4-diagrams">
<h3>System Context (C4 Level 1)</h3>
<p>High-level view of the e-commerce platform and its external dependencies.</p>
<div class="mermaid">
graph TD
Customer[Customer]
Admin[Administrator]
PaymentGateway[Payment Gateway<br/>Stripe]
EmailService[Email Service<br/>SendGrid]
System[E-Commerce Platform]
Customer -->|Browse products,<br/>Place orders| System
Admin -->|Manage products,<br/>View analytics| System
System -->|Process payments| PaymentGateway
System -->|Send notifications| EmailService
</div>
<!-- EXAMPLE END -->
<!-- PLACEHOLDER: {{C4_CONTAINER}} -->
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
<h3>Container Diagram (C4 Level 2)</h3>
<p>Containers within the e-commerce platform showing technologies and communication.</p>
<div class="mermaid">
graph TD
Customer[Customer<br/>Web Browser]
Admin[Administrator<br/>Web Browser]
WebApp[Web Application<br/>React 18 SPA]
API[REST API<br/>Node.js + Express]
Database[(Database<br/>PostgreSQL 15)]
Cache[(Cache<br/>Redis)]
Customer -->|HTTPS| WebApp
Admin -->|HTTPS| WebApp
WebApp -->|JSON/HTTPS| API
API -->|SQL| Database
API -->|Cache queries| Cache
</div>
<!-- EXAMPLE END -->
<!-- PLACEHOLDER: {{C4_COMPONENT}} -->
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
<h3>Component Diagram (C4 Level 3) - Optional for Technical Audiences</h3>
<p>Components within the REST API container showing internal structure.</p>
<div class="mermaid">
graph TD
API[REST API Container]
AuthController[Authentication<br/>Controller]
ProductController[Product Catalog<br/>Controller]
CartController[Shopping Cart<br/>Controller]
OrderController[Order<br/>Controller]
AuthService[Auth Service]
ProductService[Product Service]
CartService[Cart Service]
OrderService[Order Service]
ProductRepo[Product<br/>Repository]
UserRepo[User<br/>Repository]
CartRepo[Cart<br/>Repository]
OrderRepo[Order<br/>Repository]
Database[(PostgreSQL)]
Cache[(Redis)]
ProductController --> ProductService
CartController --> CartService
OrderController --> OrderService
AuthController --> AuthService
ProductService --> ProductRepo
CartService --> CartRepo
OrderService --> OrderRepo
AuthService --> UserRepo
ProductRepo --> Database
UserRepo --> Database
CartRepo --> Cache
OrderRepo --> Database
</div>
<!-- EXAMPLE END -->
<!-- PLACEHOLDER: {{DEPLOYMENT_DIAGRAM}} -->
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
<h3>Deployment Diagram</h3>
<p>Infrastructure and deployment architecture on AWS.</p>
<div class="mermaid">
graph TD
subgraph "AWS Cloud"
subgraph "Public Subnet"
ALB[Application Load<br/>Balancer]
CloudFront[CloudFront CDN]
end
subgraph "Private Subnet"
ECS1[ECS Container 1<br/>Node.js API]
ECS2[ECS Container 2<br/>Node.js API]
RDS[(RDS PostgreSQL<br/>Primary)]
RDSReplica[(RDS PostgreSQL<br/>Read Replica)]
ElastiCache[(ElastiCache<br/>Redis)]
end
subgraph "Storage"
S3[S3 Bucket<br/>Static Assets]
end
end
CloudFront --> S3
ALB --> ECS1
ALB --> ECS2
ECS1 --> RDS
ECS2 --> RDS
ECS1 --> RDSReplica
ECS2 --> RDSReplica
ECS1 --> ElastiCache
ECS2 --> ElastiCache
</div>
</section>
<!-- EXAMPLE END -->
<!-- PLACEHOLDER: {{ARCHITECTURE_NOTES}} -->
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
<section class="architecture-notes">
<h3>Key Architecture Highlights</h3>
<table>
<thead>
<tr>
<th>Aspect</th>
<th>Approach</th>
<th>Rationale</th>
</tr>
</thead>
<tbody>
<tr>
<td>Architecture Pattern</td>
<td>Modular Monolith</td>
<td>Clear domain boundaries (Auth, Catalog, Cart, Orders) - see ADR-001 in Requirements</td>
</tr>
<tr>
<td>API Design</td>
<td>Stateless API</td>
<td>Enables horizontal scaling without session affinity</td>
</tr>
<tr>
<td>Database Strategy</td>
<td>PostgreSQL with read replicas</td>
<td>ACID transactions + scalability through read replicas</td>
</tr>
<tr>
<td>Caching</td>
<td>Redis</td>
<td>Session/cart data and frequently accessed product catalog</td>
</tr>
<tr>
<td>Infrastructure</td>
<td>Docker containers</td>
<td>Cloud-native orchestration with Kubernetes</td>
</tr>
</tbody>
</table>
<p><em>For detailed quality attributes (Performance, Security, Scalability, Maintainability), see requirements.md in docs/project/.</em></p>
</section>
<!-- EXAMPLE END -->

198
skills/ln-115-presentation-creator/references/tabs/tab_guides.html Normal file
View File

@@ -0,0 +1,198 @@
<!-- SCOPE: How-To Guides (Practical Task Instructions) -->
<!-- INCLUDES: Step-by-step guides (Installation, Development, Deployment, Integration), Prerequisites, Verification steps, Troubleshooting, Best practices -->
<!-- EXCLUDES: Conceptual explanations → Requirements/Architecture, API reference → Technical Spec, What/Why → Requirements, System design → Architecture, Work planning → Roadmap -->
<h2>Guides & Resources</h2>
<!-- PLACEHOLDER: {{GETTING_STARTED}} -->
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
<section class="getting-started">
<h3>Getting Started</h3>
<h4>Prerequisites</h4>
<ul>
<li>Node.js 20.x or higher</li>
<li>PostgreSQL 15.x</li>
<li>Redis 7.x (optional for development)</li>
<li>Docker (optional)</li>
</ul>
<h4>Installation</h4>
<pre><code>git clone https://github.com/example/ecommerce-platform.git
cd ecommerce-platform
npm install
cp .env.example .env
# Edit .env with your database credentials
npm run db:migrate
npm run dev</code></pre>
<h4>Verification</h4>
<p>After starting the server, verify installation:</p>
<ul>
<li>✅ Server running at <code>http://localhost:3000</code></li>
<li>✅ API health check: <code>curl http://localhost:3000/api/health</code></li>
<li>✅ Database migrations applied: <code>npm run db:status</code></li>
</ul>
</section>
<!-- EXAMPLE END -->
<!-- PLACEHOLDER: {{HOW_TO_GUIDES}} -->
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
<section class="how-to-guides">
<h3>How-To Guides</h3>
<div class="card">
<h4>How to Add a New Product</h4>
<ol>
<li>Login as admin: <code>POST /api/auth/login</code> with admin credentials</li>
<li>Get JWT token from response</li>
<li>Create product:
<pre><code>curl -X POST http://localhost:3000/api/products \
-H "Authorization: Bearer &lt;token&gt;" \
-H "Content-Type: application/json" \
-d '{
"name": "Product Name",
"description": "Product Description",
"price": 29.99,
"stock_quantity": 100,
"category": "Electronics"
}'</code></pre>
</li>
<li>Verify product created: <code>GET /api/products/:id</code></li>
</ol>
</div>
<div class="card">
<h4>How to Test API Endpoints</h4>
<ol>
<li>Start development server: <code>npm run dev</code></li>
<li>Run tests:
<ul>
<li>All tests: <code>npm test</code></li>
<li>E2E tests only: <code>npm run test:e2e</code></li>
<li>Integration tests: <code>npm run test:integration</code></li>
<li>Unit tests: <code>npm run test:unit</code></li>
</ul>
</li>
<li>View coverage report: <code>npm run test:coverage</code></li>
</ol>
</div>
<div class="card">
<h4>How to Deploy to Production</h4>
<ol>
<li>Build Docker image: <code>docker build -t ecommerce-api .</code></li>
<li>Push to registry: <code>docker push ecommerce-api:latest</code></li>
<li>Update ECS task definition with new image</li>
<li>Deploy via GitHub Actions (automatic on merge to main)</li>
<li>Verify deployment: Check CloudWatch logs for startup</li>
</ol>
</div>
</section>
<!-- EXAMPLE END -->
<!-- PLACEHOLDER: {{BEST_PRACTICES}} -->
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
<section class="best-practices">
<h3>Best Practices</h3>
<h4>Code Style</h4>
<ul>
<li>Follow KISS/YAGNI/DRY principles</li>
<li>Use TypeScript for type safety</li>
<li>Keep functions small and focused (< 30 lines)</li>
<li>Use meaningful variable names (no single letters except loops)</li>
</ul>
<h4>Testing Approach</h4>
<ul>
<li>Follow Risk-Based Testing (Priority ≥ 15 scenarios MUST be tested)</li>
<li>E2E tests (2-5 per Story): Critical user flows</li>
<li>Integration tests (3-8 per Story): API endpoints</li>
<li>Unit tests (5-15 per Story): Business logic only</li>
<li>Test OUR code, not frameworks (Express already tested)</li>
</ul>
<h4>Design Patterns</h4>
<ul>
<li>Layered architecture: Controller → Service → Repository</li>
<li>Dependency Injection for testability</li>
<li>Repository pattern for database access</li>
<li>DTO (Data Transfer Objects) for API requests/responses</li>
</ul>
</section>
<!-- EXAMPLE END -->
<!-- PLACEHOLDER: {{TROUBLESHOOTING}} -->
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
<section class="troubleshooting">
<h3>Troubleshooting</h3>
<h4>Database Connection Errors</h4>
<p><strong>Problem:</strong> "Unable to connect to PostgreSQL"</p>
<p><strong>Solution:</strong></p>
<ul>
<li>Check PostgreSQL is running: <code>pg_isready</code></li>
<li>Verify .env credentials match database</li>
<li>Check firewall allows port 5432</li>
</ul>
<h4>Port Already in Use</h4>
<p><strong>Problem:</strong> "Port 3000 is already in use"</p>
<p><strong>Solution:</strong></p>
<ul>
<li>Change PORT in .env to different port (e.g., 3001)</li>
<li>Or kill process using port: <code>lsof -ti:3000 | xargs kill</code></li>
</ul>
<h4>JWT Token Expired</h4>
<p><strong>Problem:</strong> "401 Unauthorized - Token expired"</p>
<p><strong>Solution:</strong></p>
<ul>
<li>Use refresh token: <code>POST /api/auth/refresh</code> with refresh token</li>
<li>Get new access token from response</li>
<li>Tokens expire after 15 minutes for security</li>
</ul>
<h4>Tests Failing Randomly</h4>
<p><strong>Problem:</strong> Tests pass locally but fail in CI</p>
<p><strong>Solution:</strong></p>
<ul>
<li>Check test isolation (no shared state between tests)</li>
<li>Use transactions in tests (rollback after each test)</li>
<li>Seed database with consistent test data</li>
</ul>
</section>
<!-- EXAMPLE END -->
<!-- PLACEHOLDER: {{CONTRIBUTING}} -->
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
<section class="contributing">
<h3>Contributing Guidelines</h3>
<ol>
<li><strong>Fork</strong> the repository</li>
<li><strong>Create branch:</strong> <code>git checkout -b feature/your-feature</code></li>
<li><strong>Write code</strong> following style guide</li>
<li><strong>Write tests:</strong> All new code must have tests (85%+ coverage)</li>
<li><strong>Run tests:</strong> <code>npm test</code> (all must pass)</li>
<li><strong>Commit:</strong> <code>git commit -m "Add your feature"</code></li>
<li><strong>Push:</strong> <code>git push origin feature/your-feature</code></li>
<li><strong>Submit PR</strong> with description of changes</li>
</ol>
</section>
<!-- EXAMPLE END -->
<!-- PLACEHOLDER: {{EXTERNAL_RESOURCES}} -->
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
<section class="external-resources">
<h3>External Resources</h3>
<ul>
<li><a href="https://nodejs.org/docs" target="_blank">Node.js Documentation</a></li>
<li><a href="https://www.postgresql.org/docs/" target="_blank">PostgreSQL Documentation</a></li>
<li><a href="https://redis.io/docs/" target="_blank">Redis Documentation</a></li>
<li><a href="https://expressjs.com/" target="_blank">Express.js Guide</a></li>
<li><a href="https://react.dev/" target="_blank">React Documentation</a></li>
<li><a href="https://www.typescriptlang.org/docs/" target="_blank">TypeScript Handbook</a></li>
</ul>
</section>
<!-- EXAMPLE END -->

127
skills/ln-115-presentation-creator/references/tabs/tab_overview.html Normal file
View File

@@ -0,0 +1,127 @@
<!-- SCOPE: Project Overview & Navigation -->
<!-- INCLUDES: Problem statement, solution approach, business value, tech stack (list only), key stakeholders, navigation guide, quick stats -->
<!-- EXCLUDES: Detailed goals → Requirements, Architecture decisions → ADRs, Diagrams → Architecture, API details → Technical Spec, Work order → Roadmap, How-to → Guides -->
<!-- PLACEHOLDER: {{PROJECT_SUMMARY}} -->
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
<div class="project-summary">
<h2>Project Summary</h2>
<h3>The Problem</h3>
<p>Traditional e-commerce platforms struggle with scalability during peak traffic, complex payment integrations, and fragmented inventory management across multiple channels. Businesses need a unified platform that handles high concurrent loads while maintaining data consistency and security.</p>
<h3>Our Solution</h3>
<p>An enterprise-grade e-commerce platform built with modern web technologies and modular architecture. The system provides seamless online shopping experiences through stateless API design, robust payment processing with PCI DSS compliance, real-time inventory synchronization, and comprehensive customer analytics.</p>
<h3>Business Value</h3>
<ul>
<li><strong>Scalability:</strong> Support 10,000+ concurrent users with horizontal scaling</li>
<li><strong>Reliability:</strong> 99.9% uptime SLA with automated failover</li>
<li><strong>Speed to Market:</strong> Modular architecture enables rapid feature delivery</li>
<li><strong>Cost Efficiency:</strong> Optimized infrastructure reduces operational costs by 30%</li>
</ul>
</div>
<!-- EXAMPLE END -->
<!-- PLACEHOLDER: {{TECH_STACK}} -->
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
<div class="tech-stack-section">
<h2>Technology Stack</h2>
<div class="tech-badges">
<span class="tech-badge">React 18</span>
<span class="tech-badge">Node.js</span>
<span class="tech-badge">PostgreSQL</span>
<span class="tech-badge">Redis</span>
<span class="tech-badge">Docker</span>
<span class="tech-badge">TypeScript</span>
</div>
</div>
<!-- EXAMPLE END -->
<!-- PLACEHOLDER: {{STAKEHOLDERS}} -->
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
<div class="stakeholders-section">
<h2>Key Stakeholders</h2>
<div class="stakeholders-grid">
<div class="stakeholder-card">
<h3>Project Owner</h3>
<p>John Smith</p>
<p class="role">Business Sponsor</p>
</div>
<div class="stakeholder-card">
<h3>Lead Architect</h3>
<p>Jane Doe</p>
<p class="role">Technical Lead</p>
</div>
<div class="stakeholder-card">
<h3>Development Lead</h3>
<p>Alex Johnson</p>
<p class="role">Engineering Manager</p>
</div>
<div class="stakeholder-card">
<h3>Product Manager</h3>
<p>Sarah Williams</p>
<p class="role">Product Strategy</p>
</div>
</div>
</div>
<!-- EXAMPLE END -->
<!-- PLACEHOLDER: {{QUICK_FACTS}} -->
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
<div class="quick-stats">
<h2>Project Quick Facts</h2>
<div class="stats-grid">
<div class="stat-card">
<h3>In Progress</h3>
<p>Project Status</p>
</div>
<div class="stat-card">
<h3>7</h3>
<p>Total Epics</p>
</div>
<div class="stat-card">
<h3>Cloud</h3>
<p>Deployment Model</p>
</div>
<div class="stat-card">
<h3>Web + Mobile</h3>
<p>Target Platforms</p>
</div>
</div>
</div>
<!-- EXAMPLE END -->
<!-- PLACEHOLDER: {{NAVIGATION_GUIDE}} -->
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
<div class="navigation-guide">
<h2>Documentation Guide</h2>
<div class="guide-grid">
<div class="guide-card">
<h3>📋 Requirements</h3>
<p>What we're building and why - functional requirements only and architecture decisions (ADRs); Non-Functional Requirements are not produced</p>
<p class="audience"><strong>For:</strong> Product Owners, Business Analysts, Architects</p>
</div>
<div class="guide-card">
<h3>🏗️ Architecture</h3>
<p>How the system is designed - C4 diagrams showing context, containers, components, and deployment infrastructure</p>
<p class="audience"><strong>For:</strong> Architects, Technical Leads, DevOps Engineers</p>
</div>
<div class="guide-card">
<h3>⚙️ Technical Spec</h3>
<p>How to interact with the system - API documentation, data models, schemas, and infrastructure configuration</p>
<p class="audience"><strong>For:</strong> Developers, QA Engineers, Integration Teams</p>
</div>
<div class="guide-card">
<h3>🗺️ Roadmap</h3>
<p>Work order and scope boundaries - Kanban board showing epic progress, dependencies, and what's in/out of scope</p>
<p class="audience"><strong>For:</strong> Stakeholders, Project Managers, Executives</p>
</div>
<div class="guide-card">
<h3>📚 Guides</h3>
<p>How to perform practical tasks - step-by-step guides for installation, development, deployment, and integration</p>
<p class="audience"><strong>For:</strong> Developers, DevOps Engineers, New Team Members</p>
</div>
</div>
</div>
<!-- EXAMPLE END -->

210
skills/ln-115-presentation-creator/references/tabs/tab_requirements.html Normal file
View File

@@ -0,0 +1,210 @@
<!-- SCOPE: Functional Requirements & Architecture Decisions -->
<!-- INCLUDES: FRs (what we build), ADRs (why we decided), Success criteria -->
<!-- EXCLUDES: Non-Functional Requirements (forbidden), Business context → Overview, System structure → Architecture, API contracts → Technical Spec, Implementation steps → Guides -->
<h2>Requirements</h2>
<!-- PLACEHOLDER: {{FUNCTIONAL_REQUIREMENTS}} -->
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
<section class="functional-requirements">
<h3>Functional Requirements</h3>
<table>
<thead>
<tr>
<th>ID</th>
<th>Priority</th>
<th>Requirement</th>
<th>Acceptance Criteria</th>
</tr>
</thead>
<tbody>
<tr>
<td>FR-AUTH-001</td>
<td><span class="priority-must">MUST</span></td>
<td><strong>User Registration and Login</strong><br>
Users must be able to register with email/password and login to access personalized features</td>
<td>
<ul>
<li>Email validation (RFC 5322 compliant)</li>
<li>Password strength requirements (min 8 chars, uppercase, lowercase, number)</li>
<li>JWT token-based authentication</li>
</ul>
</td>
</tr>
<tr>
<td>FR-CATALOG-001</td>
<td><span class="priority-must">MUST</span></td>
<td><strong>Product Catalog Display</strong><br>
System must display product catalog with search, filters, and pagination</td>
<td>
<ul>
<li>Full-text search across product names and descriptions</li>
<li>Filter by category, price range, availability</li>
<li>Paginate results (20 items per page)</li>
</ul>
</td>
</tr>
<tr>
<td>FR-CART-001</td>
<td><span class="priority-must">MUST</span></td>
<td><strong>Shopping Cart Management</strong><br>
Users must be able to add/remove products to/from cart</td>
<td>
<ul>
<li>Add product with quantity selection</li>
<li>Update quantities in cart</li>
<li>Remove items from cart</li>
<li>Cart persists across sessions (logged-in users)</li>
</ul>
</td>
</tr>
</tbody>
</table>
</section>
<!-- EXAMPLE END -->
<!-- PLACEHOLDER: {{ADR_STRATEGIC}} -->
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
<section class="adr-section">
<h3>📋 Architecture Decision Records</h3>
<div class="adr-group">
<h4>🎯 Strategic Decisions</h4>
<details class="adr-item">
<summary>ADR-001: Microservices vs Monolith Architecture</summary>
<p><strong>Date:</strong> 2025-09-15 | <strong>Status:</strong> Accepted | <strong>Category:</strong> Strategic</p>
<h4>Context</h4>
<p>Need to choose architecture pattern for e-commerce platform considering team size, scaling requirements, and deployment complexity.</p>
<h4>Decision</h4>
<p>Use <strong>modular monolith</strong> architecture with clear domain boundaries.</p>
<h4>Rationale</h4>
<ul>
<li>Small team (5 developers) - microservices overhead too high</li>
<li>Faster time to market with simplified deployment</li>
<li>Clear module boundaries allow future microservices extraction</li>
</ul>
<h4>Alternatives Considered</h4>
<table>
<thead>
<tr>
<th>Alternative</th>
<th>Pros</th>
<th>Cons</th>
<th>Rejection Reason</th>
</tr>
</thead>
<tbody>
<tr>
<td>Microservices</td>
<td>Independent scaling, technology diversity</td>
<td>Operational complexity, team overhead</td>
<td>Team too small, premature optimization</td>
</tr>
<tr>
<td>Traditional monolith</td>
<td>Simplest to build</td>
<td>Difficult to scale, tight coupling</td>
<td>No clear boundaries for future evolution</td>
</tr>
</tbody>
</table>
<h4>Consequences</h4>
<p><strong>Positive:</strong></p>
<ul>
<li>Faster development and deployment</li>
<li>Easier testing and debugging</li>
<li>Lower infrastructure costs</li>
</ul>
<p><strong>Negative:</strong></p>
<ul>
<li>Cannot scale individual modules independently</li>
<li>Requires discipline to maintain module boundaries</li>
</ul>
</details>
</div>
<!-- EXAMPLE END -->
<!-- PLACEHOLDER: {{ADR_TECHNICAL}} -->
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
<div class="adr-group">
<h4>🔧 Technical Decisions</h4>
<details class="adr-item">
<summary>ADR-002: Database Choice - PostgreSQL vs MongoDB</summary>
<p><strong>Date:</strong> 2025-09-18 | <strong>Status:</strong> Accepted | <strong>Category:</strong> Technical</p>
<h4>Context</h4>
<p>Need to select database for e-commerce transactional data considering ACID requirements, scalability, and query complexity.</p>
<h4>Decision</h4>
<p>Use <strong>PostgreSQL 15.x</strong> as primary database.</p>
<h4>Rationale</h4>
<ul>
<li>Strong ACID guarantees for transactions (orders, payments)</li>
<li>JSON support for flexible product attributes</li>
<li>Excellent performance for complex queries</li>
</ul>
<h4>Alternatives Considered</h4>
<table>
<thead>
<tr>
<th>Alternative</th>
<th>Pros</th>
<th>Cons</th>
<th>Rejection Reason</th>
</tr>
</thead>
<tbody>
<tr>
<td>MongoDB</td>
<td>Schema flexibility, horizontal scaling</td>
<td>Weak transaction support, complex queries difficult</td>
<td>E-commerce requires strong ACID for financial data</td>
</tr>
<tr>
<td>MySQL</td>
<td>Widely adopted, good performance</td>
<td>Limited JSON support, fewer features</td>
<td>PostgreSQL offers better feature set</td>
</tr>
</tbody>
</table>
<h4>Consequences</h4>
<p><strong>Positive:</strong></p>
<ul>
<li>Data integrity guaranteed for financial transactions</li>
<li>Rich ecosystem and tooling</li>
</ul>
<p><strong>Negative:</strong></p>
<ul>
<li>Vertical scaling limitations (mitigated by read replicas)</li>
<li>Schema migrations require careful planning</li>
</ul>
</details>
</div>
</section>
<!-- EXAMPLE END -->
<!-- PLACEHOLDER: {{SUCCESS_CRITERIA}} -->
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
<section class="success-criteria">
<h3>Success Criteria</h3>
<ul>
<li>✅ MVP handles 1,000+ daily active users</li>
<li>✅ 99.5% uptime in first 3 months</li>
<li>✅ Average checkout time < 3 minutes</li>
<li>✅ 85%+ test coverage (E2E + Integration + Unit)</li>
<li>✅ Zero critical security vulnerabilities</li>
</ul>
</section>
<!-- EXAMPLE END -->

315
skills/ln-115-presentation-creator/references/tabs/tab_roadmap.html Normal file
View File

@@ -0,0 +1,315 @@
<!-- SCOPE: Work Order & Scope Boundaries (NO Dates/Budgets) -->
<!-- INCLUDES: Epic list with scope (in/out), dependencies, success criteria, status -->
<!-- EXCLUDES: Specific dates/deadlines, Budget/costs, Team assignments, Individual tasks/stories, Implementation details → Technical Spec -->
<h2>Roadmap</h2>
<p class="roadmap-intro">This roadmap shows the <strong>work order</strong> and <strong>scope boundaries</strong> for our project. Epics are organized by dependencies, with clear scope definition for each.</p>
<!-- PLACEHOLDER: {{EPIC_CARDS}} -->
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
<section class="epics-list">
<!-- Epic 1: Done -->
<div class="epic-item">
<div class="epic-header">
<h3>Epic 1: User Management</h3>
<span class="epic-status status-done">Done</span>
</div>
<p class="epic-description">User registration, authentication, profile management, and session handling</p>
<div class="epic-details">
<div class="epic-scope">
<h4>In Scope</h4>
<ul>
<li>JWT authentication</li>
<li>Email/password registration</li>
<li>Password reset flow</li>
<li>User profile CRUD operations</li>
<li>Session management</li>
</ul>
</div>
<div class="epic-scope">
<h4>Out of Scope</h4>
<ul>
<li>Social login (OAuth)</li>
<li>Multi-factor authentication</li>
<li>Single sign-on (SSO)</li>
</ul>
</div>
</div>
<div class="epic-meta">
<p><strong>Dependencies:</strong> None (Foundation epic)</p>
<p><strong>Success Criteria:</strong> JWT authentication, < 2s login time, Password reset flow</p>
<p><strong>Progress:</strong> 6/6 stories completed (100%)</p>
</div>
</div>
<!-- Epic 2: Done -->
<div class="epic-item">
<div class="epic-header">
<h3>Epic 2: Product Catalog</h3>
<span class="epic-status status-done">Done</span>
</div>
<p class="epic-description">Product listing, search, filters, and pagination</p>
<div class="epic-details">
<div class="epic-scope">
<h4>In Scope</h4>
<ul>
<li>Full-text search across product names and descriptions</li>
<li>Category filters</li>
<li>Price range filters</li>
<li>Pagination (20 items/page)</li>
<li>Product detail pages</li>
<li>1000+ SKUs support</li>
</ul>
</div>
<div class="epic-scope">
<h4>Out of Scope</h4>
<ul>
<li>AI-powered recommendations</li>
<li>Visual search</li>
<li>Product reviews</li>
</ul>
</div>
</div>
<div class="epic-meta">
<p><strong>Dependencies:</strong> Epic 1 (User Management for admin features)</p>
<p><strong>Success Criteria:</strong> Full-text search, 1000+ SKUs, < 1s search response</p>
<p><strong>Progress:</strong> 8/8 stories completed (100%)</p>
</div>
</div>
<!-- Epic 3: In Progress -->
<div class="epic-item">
<div class="epic-header">
<h3>Epic 3: Shopping Cart</h3>
<span class="epic-status status-progress">In Progress</span>
</div>
<p class="epic-description">Cart management with session persistence and inventory validation</p>
<div class="epic-details">
<div class="epic-scope">
<h4>In Scope</h4>
<ul>
<li>Add/remove items from cart</li>
<li>Update quantities</li>
<li>Cart persistence across sessions</li>
<li>Real-time inventory validation</li>
<li>Cart subtotal calculation</li>
</ul>
</div>
<div class="epic-scope">
<h4>Out of Scope</h4>
<ul>
<li>Wishlist functionality</li>
<li>Share cart</li>
<li>Save for later</li>
</ul>
</div>
</div>
<div class="epic-meta">
<p><strong>Dependencies:</strong> Epic 2 (Product Catalog)</p>
<p><strong>Success Criteria:</strong> Cart persists across sessions, real-time inventory sync, < 500ms cart operations</p>
<p><strong>Progress:</strong> 3/8 stories completed (37%)</p>
</div>
</div>
<!-- Epic 4: In Progress -->
<div class="epic-item">
<div class="epic-header">
<h3>Epic 4: Admin Dashboard</h3>
<span class="epic-status status-progress">In Progress</span>
</div>
<p class="epic-description">Product management, inventory control, and analytics dashboard</p>
<div class="epic-details">
<div class="epic-scope">
<h4>In Scope</h4>
<ul>
<li>Product CRUD operations</li>
<li>Bulk product import (CSV)</li>
<li>Inventory management</li>
<li>Role-based access control</li>
<li>Real-time analytics dashboard</li>
<li>Sales reports</li>
</ul>
</div>
<div class="epic-scope">
<h4>Out of Scope</h4>
<ul>
<li>Customer support tickets</li>
<li>Email campaigns</li>
<li>Advanced BI reports</li>
</ul>
</div>
</div>
<div class="epic-meta">
<p><strong>Dependencies:</strong> Epic 1 (User Management), Epic 2 (Product Catalog)</p>
<p><strong>Success Criteria:</strong> Role-based access control, bulk product import, real-time analytics</p>
<p><strong>Progress:</strong> 2/7 stories completed (28%)</p>
</div>
</div>
<!-- Epic 5: Todo -->
<div class="epic-item">
<div class="epic-header">
<h3>Epic 5: Payment Gateway</h3>
<span class="epic-status status-todo">Todo</span>
</div>
<p class="epic-description">Integrate Stripe for secure payment processing with PCI DSS compliance</p>
<div class="epic-details">
<div class="epic-scope">
<h4>In Scope</h4>
<ul>
<li>Stripe payment integration</li>
<li>Credit/debit card payments</li>
<li>Digital wallets (Apple Pay, Google Pay)</li>
<li>PCI DSS compliance</li>
<li>Payment error handling</li>
<li>Refund processing</li>
</ul>
</div>
<div class="epic-scope">
<h4>Out of Scope</h4>
<ul>
<li>Cryptocurrency payments</li>
<li>Buy now, pay later (BNPL)</li>
<li>Invoice payments</li>
</ul>
</div>
</div>
<div class="epic-meta">
<p><strong>Dependencies:</strong> Epic 3 (Shopping Cart)</p>
<p><strong>Success Criteria:</strong> PCI DSS compliant, < 3s checkout time, support 5+ payment methods</p>
<p><strong>Progress:</strong> 0/5 stories planned</p>
</div>
</div>
<!-- Epic 6: Todo -->
<div class="epic-item">
<div class="epic-header">
<h3>Epic 6: Order Management</h3>
<span class="epic-status status-todo">Todo</span>
</div>
<p class="epic-description">Order processing, tracking, and fulfillment workflows</p>
<div class="epic-details">
<div class="epic-scope">
<h4>In Scope</h4>
<ul>
<li>Order creation and confirmation</li>
<li>Real-time order tracking</li>
<li>Email notifications</li>
<li>Order history</li>
<li>Automated fulfillment workflows</li>
<li>Cancellation and refund flows</li>
</ul>
</div>
<div class="epic-scope">
<h4>Out of Scope</h4>
<ul>
<li>Advanced shipping integrations</li>
<li>Returns management portal</li>
<li>International shipping</li>
</ul>
</div>
</div>
<div class="epic-meta">
<p><strong>Dependencies:</strong> Epic 5 (Payment Gateway)</p>
<p><strong>Success Criteria:</strong> Real-time order tracking, automated fulfillment notifications, < 1min order confirmation</p>
<p><strong>Progress:</strong> 0/6 stories planned</p>
</div>
</div>
<!-- Epic 7: Backlog -->
<div class="epic-item">
<div class="epic-header">
<h3>Epic 7: Advanced Analytics</h3>
<span class="epic-status status-backlog">Backlog</span>
</div>
<p class="epic-description">Customer behavior analytics and recommendations engine</p>
<div class="epic-details">
<div class="epic-scope">
<h4>In Scope</h4>
<ul>
<li>Customer behavior tracking</li>
<li>Product recommendations engine</li>
<li>Conversion funnel analytics</li>
<li>A/B testing framework</li>
<li>Personalized user experience</li>
</ul>
</div>
<div class="epic-scope">
<h4>Out of Scope</h4>
<ul>
<li>Machine learning models</li>
<li>Predictive analytics</li>
<li>Customer data platform (CDP)</li>
</ul>
</div>
</div>
<div class="epic-meta">
<p><strong>Dependencies:</strong> Epic 2 (Product Catalog), Epic 6 (Order Management)</p>
<p><strong>Success Criteria:</strong> 15% increase in conversion rate, personalized recommendations for 80%+ users</p>
<p><strong>Progress:</strong> 0/9 stories planned</p>
</div>
</div>
</section>
<!-- EXAMPLE END -->
<!-- PLACEHOLDER: {{OUT_OF_SCOPE_ITEMS}} -->
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
<section class="out-of-scope-items">
<h3>Out of Project Scope</h3>
<p>The following items are explicitly <strong>NOT included</strong> in the current project phase:</p>
<div class="out-of-scope-grid">
<div class="out-of-scope-card">
<h4>Mobile Native Apps</h4>
<p>iOS and Android native applications</p>
<p class="scope-reason"><strong>Reason:</strong> Focus on responsive web first, native apps planned for Phase 2</p>
</div>
<div class="out-of-scope-card">
<h4>Multi-Currency Support</h4>
<p>International payments and currency conversion</p>
<p class="scope-reason"><strong>Reason:</strong> Current scope limited to USD, internationalization in future release</p>
</div>
<div class="out-of-scope-card">
<h4>Social Commerce Integration</h4>
<p>Social media selling and live shopping features</p>
<p class="scope-reason"><strong>Reason:</strong> Not in MVP scope, evaluate after core features stable</p>
</div>
<div class="out-of-scope-card">
<h4>B2B Wholesale Portal</h4>
<p>Bulk ordering and wholesale pricing for business customers</p>
<p class="scope-reason"><strong>Reason:</strong> B2C focus first, B2B features separate project phase</p>
</div>
</div>
</section>
<!-- EXAMPLE END -->
<!-- PLACEHOLDER: {{ROADMAP_LEGEND}} -->
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
<section class="roadmap-legend">
<h3>Status Legend</h3>
<div class="status-badges">
<span class="epic-status status-done">Done</span> Completed and deployed
<span class="epic-status status-progress">In Progress</span> Currently being developed
<span class="epic-status status-todo">Todo</span> Approved and ready to start
<span class="epic-status status-backlog">Backlog</span> Under evaluation
</div>
</section>
<!-- EXAMPLE END -->

364
skills/ln-115-presentation-creator/references/tabs/tab_technical_spec.html Normal file
View File

@@ -0,0 +1,364 @@
<!-- SCOPE: API Documentation & Technical Reference -->
<!-- INCLUDES: API endpoints (methods, parameters, responses), Data models (schemas, ER diagrams), Infrastructure configuration, Deployment setup, Integration specifications -->
<!-- EXCLUDES: Technology decisions → ADRs in Requirements, Business requirements → Requirements tab, System diagrams → Architecture, Work order → Roadmap, How-to tutorials → Guides -->
<h2>Technical Specification</h2>
<!-- PLACEHOLDER: {{TECH_STACK_TABLE}} -->
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
<section class="tech-stack">
<h3>Technology Stack</h3>
<table>
<thead>
<tr>
<th>Category</th>
<th>Technology</th>
<th>Version</th>
<th>Purpose</th>
</tr>
</thead>
<tbody>
<tr>
<td>Frontend</td>
<td>React</td>
<td>18.2</td>
<td>UI framework for SPA</td>
</tr>
<tr>
<td>Frontend</td>
<td>TypeScript</td>
<td>5.2</td>
<td>Type-safe JavaScript</td>
</tr>
<tr>
<td>Backend</td>
<td>Node.js</td>
<td>20.x</td>
<td>Runtime environment</td>
</tr>
<tr>
<td>Backend</td>
<td>Express</td>
<td>4.18</td>
<td>REST API framework</td>
</tr>
<tr>
<td>Database</td>
<td>PostgreSQL</td>
<td>15.x</td>
<td>Primary transactional database</td>
</tr>
<tr>
<td>Cache</td>
<td>Redis</td>
<td>7.x</td>
<td>Session & cart caching</td>
</tr>
<tr>
<td>Infrastructure</td>
<td>Docker</td>
<td>24.x</td>
<td>Containerization</td>
</tr>
<tr>
<td>Infrastructure</td>
<td>AWS ECS</td>
<td>-</td>
<td>Container orchestration</td>
</tr>
<tr>
<td>DevOps</td>
<td>GitHub Actions</td>
<td>-</td>
<td>CI/CD pipeline</td>
</tr>
</tbody>
</table>
</section>
<!-- EXAMPLE END -->
<!-- PLACEHOLDER: {{API_ENDPOINTS}} -->
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
<section class="api-reference">
<h3>API Endpoints</h3>
<h4>Authentication</h4>
<table>
<thead>
<tr>
<th>Endpoint</th>
<th>Method</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>/api/auth/register</code></td>
<td>POST</td>
<td>Register new user</td>
</tr>
<tr>
<td><code>/api/auth/login</code></td>
<td>POST</td>
<td>Login and get JWT token</td>
</tr>
<tr>
<td><code>/api/auth/refresh</code></td>
<td>POST</td>
<td>Refresh JWT token</td>
</tr>
</tbody>
</table>
<h4>Products</h4>
<table>
<thead>
<tr>
<th>Endpoint</th>
<th>Method</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>/api/products</code></td>
<td>GET</td>
<td>List all products (paginated)</td>
</tr>
<tr>
<td><code>/api/products/:id</code></td>
<td>GET</td>
<td>Get product details</td>
</tr>
<tr>
<td><code>/api/products</code></td>
<td>POST</td>
<td>Create new product (admin only)</td>
</tr>
<tr>
<td><code>/api/products/:id</code></td>
<td>PUT</td>
<td>Update product (admin only)</td>
</tr>
</tbody>
</table>
<h4>Shopping Cart</h4>
<table>
<thead>
<tr>
<th>Endpoint</th>
<th>Method</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>/api/cart</code></td>
<td>GET</td>
<td>Get current user's cart</td>
</tr>
<tr>
<td><code>/api/cart/items</code></td>
<td>POST</td>
<td>Add item to cart</td>
</tr>
<tr>
<td><code>/api/cart/items/:id</code></td>
<td>PUT</td>
<td>Update item quantity</td>
</tr>
<tr>
<td><code>/api/cart/items/:id</code></td>
<td>DELETE</td>
<td>Remove item from cart</td>
</tr>
</tbody>
</table>
<h4>Authentication</h4>
<p><strong>Method:</strong> JWT Bearer Token</p>
<pre><code>Authorization: Bearer &lt;token&gt;</code></pre>
<p>Token expires in 15 minutes. Use <code>/api/auth/refresh</code> with refresh token to get new access token.</p>
<h4>Error Codes</h4>
<table>
<thead>
<tr>
<th>Code</th>
<th>Message</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>400</td>
<td>Bad Request</td>
<td>Invalid request payload</td>
</tr>
<tr>
<td>401</td>
<td>Unauthorized</td>
<td>Missing or invalid JWT token</td>
</tr>
<tr>
<td>403</td>
<td>Forbidden</td>
<td>Insufficient permissions</td>
</tr>
<tr>
<td>404</td>
<td>Not Found</td>
<td>Resource not found</td>
</tr>
<tr>
<td>500</td>
<td>Internal Server Error</td>
<td>Unexpected server error</td>
</tr>
</tbody>
</table>
</section>
<!-- EXAMPLE END -->
<!-- PLACEHOLDER: {{DATA_MODELS}} -->
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
<section class="data-models">
<h3>Data Models</h3>
<h4>Entity Relationship Diagram</h4>
<div class="mermaid">
erDiagram
USER ||--o{ ORDER : places
USER ||--o{ CART : has
CART ||--|{ CART_ITEM : contains
PRODUCT ||--o{ CART_ITEM : "in"
PRODUCT ||--o{ ORDER_ITEM : "in"
ORDER ||--|{ ORDER_ITEM : contains
ORDER ||--|| PAYMENT : has
USER {
uuid id PK
string email
string password_hash
string first_name
string last_name
timestamp created_at
}
PRODUCT {
uuid id PK
string name
text description
decimal price
int stock_quantity
string category
timestamp created_at
}
CART {
uuid id PK
uuid user_id FK
timestamp updated_at
}
CART_ITEM {
uuid id PK
uuid cart_id FK
uuid product_id FK
int quantity
}
ORDER {
uuid id PK
uuid user_id FK
decimal total_amount
string status
timestamp created_at
}
ORDER_ITEM {
uuid id PK
uuid order_id FK
uuid product_id FK
int quantity
decimal price_at_purchase
}
PAYMENT {
uuid id PK
uuid order_id FK
string payment_method
string status
string transaction_id
timestamp created_at
}
</div>
<h4>Data Dictionary</h4>
<table>
<thead>
<tr>
<th>Entity</th>
<th>Key Attributes</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>USER</td>
<td>email (unique), password_hash</td>
<td>Customer accounts</td>
</tr>
<tr>
<td>PRODUCT</td>
<td>name, price, stock_quantity</td>
<td>Product catalog items</td>
</tr>
<tr>
<td>CART</td>
<td>user_id</td>
<td>Shopping cart (1 per user)</td>
</tr>
<tr>
<td>ORDER</td>
<td>user_id, status, total_amount</td>
<td>Customer orders</td>
</tr>
<tr>
<td>PAYMENT</td>
<td>order_id, transaction_id, status</td>
<td>Payment transactions</td>
</tr>
</tbody>
</table>
</section>
<!-- EXAMPLE END -->
<!-- PLACEHOLDER: {{TESTING_STRATEGY}} -->
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
<section class="testing-strategy">
<h3>Testing Strategy</h3>
<p><strong>Risk-Based Testing approach</strong> - prioritize tests by business impact:</p>
<h4>Test Pyramid</h4>
<ul>
<li><strong>E2E Tests (2-5 per Story):</strong> Critical user flows (checkout, payment, registration)</li>
<li><strong>Integration Tests (3-8 per Story):</strong> API endpoints, database interactions</li>
<li><strong>Unit Tests (5-15 per Story):</strong> Business logic, validators, utilities</li>
</ul>
<p><strong>Total:</strong> 10-28 tests per Story (max)</p>
<h4>Priority Matrix</h4>
<p>Test scenarios with <strong>Priority ≥ 15</strong> MUST be tested:</p>
<pre><code>Priority = Business Impact (1-5) × Probability (1-5)</code></pre>
<h4>Test Focus</h4>
<ul>
<li>✅ Test OUR code (business logic, API endpoints)</li>
<li>❌ Skip framework code (Express middleware already tested)</li>
<li>❌ Skip trivial getters/setters (no business logic)</li>
</ul>
</section>
<!-- EXAMPLE END -->

440
skills/ln-116-test-docs-creator/SKILL.md Normal file
View File

@@ -0,0 +1,440 @@
---
name: ln-116-test-docs-creator
description: Creates test documentation (testing-strategy.md + tests/README.md). Establishes testing philosophy and Story-Level Test Task Pattern. Part of ln-110-documents-pipeline workflow.
---
# Test Documentation Creator
This skill creates and validates test documentation: testing-strategy.md (universal testing philosophy) + tests/README.md (test organization structure and Story-Level Test Task Pattern).
## When to Use This Skill
**This skill is a WORKER** invoked by **ln-110-documents-pipeline** orchestrator.
This skill should be used directly when:
- Creating only test documentation (testing-strategy.md + tests/README.md)
- Validating existing test documentation structure and content
- Setting up test philosophy and structure documentation for existing project
- NOT creating full documentation structure (use ln-110-documents-pipeline for complete setup)
## How It Works
The skill follows a 3-phase workflow: **CREATE** → **VALIDATE STRUCTURE** → **VALIDATE CONTENT**. Each phase builds on the previous, ensuring complete structure and semantic validation.
---
### Phase 1: Create Test Documentation
**Objective**: Establish test philosophy and documentation structure.
**Process**:
**1.1 Check & create directories**:
- Check if `docs/reference/guides/` exists → create if missing
- Check if `tests/` exists → create if missing
- Log for each: "✓ Created [directory]/" or "✓ [directory]/ already exists"
**1.2 Check & create documentation files**:
- Check if `docs/reference/guides/testing-strategy.md` exists
- If exists:
- Skip creation
- Log: "✓ testing-strategy.md already exists, proceeding to validation"
- If NOT exists:
- Copy template: `ln-116-test-docs-creator/references/testing_strategy_template.md` → `docs/reference/guides/testing-strategy.md`
- Replace placeholders:
- `[CURRENT_DATE]` — current date (YYYY-MM-DD)
- Log: "✓ Created testing-strategy.md from template"
- Check if `tests/README.md` exists
- If exists:
- Skip creation
- Log: "✓ tests/README.md already exists, proceeding to validation"
- If NOT exists:
- Copy template: `ln-116-test-docs-creator/references/tests_readme_template.md` → `tests/README.md`
- Replace placeholders:
- `{{DATE}}` — current date (YYYY-MM-DD)
- Log: "✓ Created tests/README.md from template"
**1.3 Output**:
```
docs/reference/guides/
└── testing-strategy.md # Created or existing
tests/
└── README.md # Created or existing
```
---
### Phase 2: Validate Structure
**Objective**: Ensure test documentation files comply with structural requirements and auto-fix violations.
**Process**:
**2.1 Check SCOPE tags**:
- Read both files (testing-strategy.md, tests/README.md) - first 5 lines only
- Check for `<!-- SCOPE: ... -->` tag in each
- Expected SCOPE tags:
- testing-strategy.md: `<!-- SCOPE: Universal testing philosophy (Risk-Based Testing, test pyramid, isolation patterns) -->`
- tests/README.md: `<!-- SCOPE: Test organization structure (directory layout, Story-Level Test Task Pattern) -->`
- If missing in either file:
- Use Edit tool to add SCOPE tag at line 1 (before first heading)
- Track violation: `scope_tags_added += 1`
**2.2 Check required sections**:
- Load expected sections from `references/questions.md`
- For **testing-strategy.md**, required sections:
- "Testing Philosophy"
- "Test Levels"
- For **tests/README.md**, required sections:
- "Test Organization"
- "Running Tests"
- For each file:
- Read file content
- Check if `## [Section Name]` header exists
- If missing:
- Use Edit tool to add section with placeholder content from template
- Track violation: `missing_sections += 1`
**2.3 Check Maintenance section**:
- For each file (testing-strategy.md, tests/README.md):
- Search for `## Maintenance` header
- If missing:
- Use Edit tool to add at end of file:
```markdown
## Maintenance
**Last Updated:** [current date]
**Update Triggers:**
- Test framework changes
- Test organization changes
- New test patterns introduced
**Verification:**
- [ ] All test examples follow current framework syntax
- [ ] Directory structure matches actual tests/
- [ ] Test runner commands are current
```
- Track violation: `maintenance_added += 1`
**2.4 Check POSIX file endings**:
- For each file:
- Check if file ends with single blank line (LF)
- If missing:
- Use Edit tool to add final newline
- Track fix: `posix_fixed += 1`
**2.5 Report validation**:
- Log summary:
```
✅ Structure validation complete:
- SCOPE tags: [added N / already present]
- Missing sections: [added N sections]
- Maintenance sections: [added N / already present]
- POSIX endings: [fixed N / compliant]
```
- If violations found: "⚠️ Auto-fixed [total] structural violations"
---
### Phase 3: Validate Content
**Objective**: Ensure each section answers its questions with meaningful content and populate test-specific sections from auto-discovery.
**Process**:
**3.1 Load validation spec**:
- Read `references/questions.md`
- Parse questions and validation heuristics for 4 sections (2 per file)
**3.2 Validate testing-strategy.md sections**:
For this file, use **standard template content** (no auto-discovery needed):
1. **Testing Philosophy section**:
- Read section content
- Check validation heuristics from questions.md:
- ✅ Mentions "Risk-Based Testing"
- ✅ Has test pyramid description
- ✅ Mentions priority threshold (≥15)
- ✅ References Story-Level Test Task Pattern
- ✅ Length > 100 words
- If ANY heuristic passes → content valid
- If ALL fail → log warning: "⚠️ testing-strategy.md → Testing Philosophy section may need review"
2. **Test Levels section**:
- Read section content
- Check validation heuristics from questions.md:
- ✅ Lists 3 levels (E2E, Integration, Unit)
- ✅ Has numeric ranges (2-5, 3-8, 5-15)
- ✅ Explains rationale
- ✅ Length > 150 words
- If ANY heuristic passes → content valid
- If ALL fail → log warning: "⚠️ testing-strategy.md → Test Levels section may need review"
**Note**: testing-strategy.md is **universal philosophy** - no project-specific auto-discovery needed.
**3.3 Validate tests/README.md sections with auto-discovery**:
**Section: Test Organization**
1. **Auto-discover test framework**:
- Check `package.json` → "devDependencies" and "dependencies":
- Node.js frameworks: jest, vitest, mocha, ava, tap, jasmine
- If found: Extract name and version
- Check `requirements.txt` (if Python project):
- Python frameworks: pytest, nose2, unittest2
- If found: Extract name and version
- Check `go.mod` (if Go project):
- Go uses built-in testing package
- If framework detected:
- Log: "✓ Test framework detected: [framework]@[version]"
- Track: `framework_detected = "[framework]"`
- If NOT detected:
- Log: "⚠️ No test framework detected. Will use generic test organization."
- Track: `framework_detected = None`
2. **Auto-discover test directory structure**:
- Use Glob tool to scan tests/ directory:
- Pattern: `"tests/e2e/**/*.{js,ts,py,go}"`
- Pattern: `"tests/integration/**/*.{js,ts,py,go}"`
- Pattern: `"tests/unit/**/*.{js,ts,py,go}"`
- Count files in each directory:
- `e2e_count = len(e2e_files)`
- `integration_count = len(integration_files)`
- `unit_count = len(unit_files)`
- If directories exist:
- Log: "✓ Test structure: [e2e_count] E2E, [integration_count] Integration, [unit_count] Unit tests"
- If directories DON'T exist:
- Create placeholder structure:
```
tests/
e2e/ (empty, ready for E2E tests)
integration/ (empty, ready for Integration tests)
unit/ (empty, ready for Unit tests)
```
- Log: "✓ Created test directory structure (will be populated during Story test task execution)"
3. **Auto-discover naming conventions**:
- For each test file found (from step 2):
- Extract filename pattern:
- `*.test.js` → "*.test.js" convention
- `*.spec.ts` → "*.spec.ts" convention
- `test_*.py` → "test_*.py" convention
- `*_test.go` → "*_test.go" convention
- Count occurrences of each pattern
- Use most common pattern (majority rule)
- If pattern detected:
- Log: "✓ Naming convention: [pattern] (detected from [count] files)"
- If NO files exist:
- Use framework default:
- Jest/Vitest → *.test.js
- Mocha → *.spec.js
- Pytest → test_*.py
- Go → *_test.go
- Log: "✓ Naming convention: [default_pattern] (framework default)"
4. **Check Test Organization section content**:
- Read section from tests/README.md
- Check validation heuristics:
- ✅ Describes directory structure (e2e/integration/unit)
- ✅ Mentions naming conventions
- ✅ References Story-Level Test Task Pattern
- ✅ Has framework mention
- If ANY heuristic passes → content valid
- If ALL fail → log warning: "⚠️ tests/README.md → Test Organization section needs update"
**Section: Running Tests**
1. **Auto-discover test runner command**:
- Read `package.json` → "scripts" → "test"
- If found:
- Extract command value
- Examples:
- `"jest"` → Test runner: "npm test" (runs jest)
- `"vitest"` → Test runner: "npm test" (runs vitest)
- `"mocha"` → Test runner: "npm test" (runs mocha)
- Custom script → Test runner: "npm test" (runs [custom])
- Log: "✓ Test runner: npm test (runs [command])"
- If NOT found (no package.json or no test script):
- Use default based on detected framework (from step 3.3.1):
- Jest → "npm test"
- Vitest → "npm test"
- Pytest → "pytest"
- Go → "go test ./..."
- Log: "⚠️ No test script found in package.json. Using default '[command]'."
2. **Auto-discover coverage command** (optional):
- Check `package.json` → "scripts" for:
- "test:coverage"
- "coverage"
- "test:cov"
- If found:
- Extract command
- Log: "✓ Coverage command: npm run [script_name]"
- If NOT found:
- Use framework default:
- Jest → "npm test -- --coverage"
- Vitest → "npm test -- --coverage"
- Pytest → "pytest --cov=src"
- Go → "go test -cover ./..."
- Log: "✓ Coverage command: [default] (framework default)"
3. **Check Running Tests section content**:
- Read section from tests/README.md
- Check validation heuristics:
- ✅ Has test runner command
- ✅ Mentions coverage
- ✅ Shows how to run specific tests
- ✅ Has command examples
- If ANY heuristic passes → content valid
- If ALL fail → log warning: "⚠️ tests/README.md → Running Tests section needs update"
**3.4 Report content validation**:
- Log summary:
```
✅ Content validation complete:
- testing-strategy.md: [2 sections checked]
- tests/README.md: [2 sections checked]
- Test framework: [detected framework or "Not detected"]
- Test structure: [e2e/integration/unit counts or "Created placeholder"]
- Naming convention: [pattern or "Framework default"]
- Test runner: [command]
- Coverage command: [command]
```
---
## Complete Output Structure
```
docs/reference/guides/
└── testing-strategy.md # Universal testing philosophy (465 lines)
tests/
└── README.md # Test organization + Story-Level Pattern (112 lines)
```
**Note**: Actual test directories (e2e/, integration/, unit/) created during Story test task execution or Phase 3 if missing.
---
## Reference Files Used
### Templates
**Testing Strategy Template**:
- `references/testing_strategy_template.md` - Universal testing philosophy with:
- SCOPE tags (testing philosophy, NOT framework-specific)
- Core Philosophy ("Test YOUR code, not frameworks")
- Risk-Based Testing Strategy (Priority Matrix, test caps)
- Story-Level Testing Pattern
- Test Organization (E2E/Integration/Unit definitions)
- Isolation Patterns (Data Deletion/Transaction Rollback/DB Recreation)
- What To Test vs NOT Test (universal examples)
- Testing Patterns (Arrange-Act-Assert, Mock at the Seam, Test Data Builders)
- Common Issues (Flaky Tests, Slow Tests, Test Coupling)
- Coverage Guidelines
- Verification Checklist
**Tests README Template**:
- `references/tests_readme_template.md` - Test organization with:
- SCOPE tags (test documentation ONLY)
- Overview (E2E/Integration/Unit test organization)
- Testing Philosophy (brief, link to testing-strategy.md)
- Test Structure (directory tree)
- Story-Level Test Task Pattern (tests in final Story task, NOT scattered)
- Test Execution (project-specific commands)
- Quick Navigation (links to testing-strategy.md, kanban_board, guidelines)
- Maintenance section (Update Triggers, Verification, Last Updated)
**Validation Specification**:
- `references/questions.md` (v1.0.0) - Question-driven validation:
- Questions each section must answer (4 sections total)
- Validation heuristics (ANY passes → valid)
- Auto-discovery hints (test frameworks, directory structure, naming conventions)
- MCP Ref hints (external research if needed)
---
## Best Practices
- **No premature validation**: Phase 1 creates structure, Phase 2 validates it (no duplicate checks)
- **Parametric validation**: Phase 3 validates 4 sections across 2 files (no code duplication)
- **Auto-discovery first**: Scan test frameworks and directory structure before using defaults
- **Idempotent**: ✅ Can run multiple times safely (checks existence before creation, re-validates on each run)
- **Separation of concerns**: CREATE → VALIDATE STRUCTURE → VALIDATE CONTENT
- **Story-Level Test Task Pattern**: Tests consolidated in final Story task (ln-350-story-test-planner creates task, ln-334-test-executor implements)
- **Value-Based Testing**: 2-5 E2E, 3-8 Integration, 5-15 Unit per Story (10-28 total max), Priority ≥15 MUST be tested
- **No test code**: This skill creates DOCUMENTATION only, NOT actual tests
---
## Prerequisites
**Invoked by**: ln-110-documents-pipeline orchestrator
**Requires**:
- `docs/reference/guides/` directory (created by ln-112-reference-docs-creator or Phase 1 if missing)
**Creates**:
- `docs/reference/guides/testing-strategy.md` (universal testing philosophy)
- `tests/README.md` (test organization structure)
- Validated structure and content (auto-discovery of test frameworks and directory structure)
---
## Definition of Done
Before completing work, verify ALL checkpoints:
**✅ Structure Created (Phase 1):**
- [ ] `docs/reference/guides/` directory exists
- [ ] `tests/` directory exists
- [ ] `testing-strategy.md` exists (created or existing)
- [ ] `tests/README.md` exists (created or existing)
**✅ Structure Validated (Phase 2):**
- [ ] SCOPE tags present in both files (first 5 lines)
- [ ] testing-strategy.md has "Testing Philosophy" and "Test Levels" sections
- [ ] tests/README.md has "Test Organization" and "Running Tests" sections
- [ ] Maintenance sections present in both files at end
- [ ] POSIX file endings compliant (LF, single blank line at EOF)
**✅ Content Validated (Phase 3):**
- [ ] testing-strategy.md → Testing Philosophy section checked (Risk-Based Testing mentioned)
- [ ] testing-strategy.md → Test Levels section checked (2-5 E2E, 3-8 Integration, 5-15 Unit)
- [ ] tests/README.md → Test Organization section checked or auto-discovered
- [ ] tests/README.md → Running Tests section checked or auto-discovered
- [ ] Test framework detected (if applicable) and logged
- [ ] Test directory structure scanned or created
- [ ] Naming conventions detected or defaults used
- [ ] Test runner command identified or defaults used
**✅ Reporting:**
- [ ] Phase 1 logged: creation summary
- [ ] Phase 2 logged: structural fixes (if any)
- [ ] Phase 3 logged: content validation summary with auto-discovery results
---
## Technical Details
**Standards**:
- Story-Level Test Task Pattern
- Value-Based Testing (2-5 E2E, 3-8 Integration, 5-15 Unit, 10-28 total max per Story)
- Risk-Based Testing (Priority ≥15)
**Language**: English only
**Auto-Discovery Support**:
- Node.js: jest, vitest, mocha, ava, tap, jasmine
- Python: pytest, nose2, unittest2
- Go: built-in testing package
---
**Version:** 7.0.0 (MAJOR: Merged validation into worker. Added Phase 2 structure validation + Phase 3 semantic content validation with test framework auto-discovery. Idempotent - can be invoked multiple times.)
**Last Updated:** 2025-11-18

126
skills/ln-116-test-docs-creator/diagram.html Normal file
View File

@@ -0,0 +1,126 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>ln-116-test-docs-creator - State Diagram</title>
<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
<link rel="stylesheet" href="../shared/css/diagram.css">
</head>
<body>
<div class="container">
<header>
<h1>🧪 ln-116-test-docs-creator</h1>
<p class="subtitle">Test Documentation Creator - State Diagram</p>
</header>
<div class="info-box">
<h3>📋 Workflow Overview</h3>
<ul>
<li><strong>Purpose:</strong> Create and validate test documentation (testing-strategy.md + tests/README.md)</li>
<li><strong>Worker for:</strong> ln-110-documents-pipeline orchestrator</li>
<li><strong>Phases:</strong> 3 phases (Phase 1 CREATE → Phase 2 Structure Validation → Phase 3 Content Validation)</li>
<li><strong>Auto-Discovery:</strong> Test framework detection, directory structure scanning, naming convention detection</li>
<li><strong>Risk-Based Testing:</strong> Priority ≥15 scenarios, test caps (2-5 E2E, 3-8 Integration, 5-15 Unit)</li>
</ul>
</div>
<div class="legend">
<div class="legend-item">
<div class="legend-color color-action"></div>
<span>Creation Action</span>
</div>
<div class="legend-item">
<div class="legend-color color-validation"></div>
<span>Validation</span>
</div>
<div class="legend-item">
<div class="legend-color color-decision"></div>
<span>Decision Point</span>
</div>
</div>
<div class="diagram-container">
<div class="mermaid">
graph TD
Start([Start: Test Docs Creation]) --> Phase1[Phase 1: CREATE<br/>Check & create test documentation]
Phase1 --> CheckDirs[Check directories:<br/>docs/reference/guides/, tests/]
CheckDirs --> CreateDirs{Directories<br/>exist?}
CreateDirs -->|No| MakeDirs[Create missing directories]
CreateDirs -->|Yes| CheckFiles
MakeDirs --> CheckFiles
CheckFiles[Check files:<br/>testing-strategy.md, tests/README.md]
CheckFiles --> FilesExist{Files<br/>exist?}
FilesExist -->|Yes| Preserved[Preserve existing files<br/>Skip creation]
FilesExist -->|No| CreateFiles[Create from templates<br/>Replace DATE placeholders]
Preserved --> Phase2
CreateFiles --> Phase2
Phase2[Phase 2: Validate Structure<br/>Auto-fix violations]
Phase2 --> AutoFix[Auto-fix:<br/>SCOPE tags, required sections,<br/>Maintenance sections, POSIX endings]
AutoFix --> Phase3[Phase 3: Validate Content<br/>Semantic validation + auto-discovery]
Phase3 --> ValidateStrategy[Validate testing-strategy.md:<br/>Testing Philosophy, Test Levels]
Phase3 --> AutoDiscovery[Auto-discovery for tests/README.md]
AutoDiscovery --> FrameworkDetect[Detect framework:<br/>package.json jest/vitest<br/>requirements.txt pytest<br/>go.mod built-in]
FrameworkDetect --> StructureScan[Scan test directory structure:<br/>tests/e2e/, tests/integration/, tests/unit/]
StructureScan --> NamingDetect[Detect naming conventions:<br/>*.test.js, *.spec.ts, test_*.py, *_test.go]
NamingDetect --> ValidateReadme[Validate tests/README.md sections:<br/>Test Organization, Running Tests]
ValidateStrategy --> Summary
ValidateReadme --> Summary
Summary[Display completion summary:<br/>Files created/preserved,<br/>Framework detected,<br/>Structure validated]
Summary --> End([End: ✓ Test docs created + validated])
%% Styling
classDef action fill:#C8E6C9,stroke:#388E3C,stroke-width:2px
classDef validation fill:#FFF9C4,stroke:#F57C00,stroke-width:2px
classDef decision fill:#FFE0B2,stroke:#E64A19,stroke-width:2px
class Phase1,CheckDirs,MakeDirs,CheckFiles,CreateFiles,Preserved,AutoFix,FrameworkDetect,StructureScan,NamingDetect,Summary action
class Phase2,Phase3,ValidateStrategy,AutoDiscovery,ValidateReadme validation
class CreateDirs,FilesExist decision
</div>
</div>
<div class="info-box">
<h3>🔑 Key Features</h3>
<ul>
<li><strong>Sixth Worker:</strong> Creates test documentation after presentation (ln-110 → ln-111 → ln-112 → ln-113 → ln-114 → ln-115 → ln-116)</li>
<li><strong>Two Files:</strong> testing-strategy.md (universal philosophy) + tests/README.md (organization with framework-specific details)</li>
<li><strong>Universal Philosophy:</strong> testing-strategy.md is framework-agnostic (Risk-Based Testing, test pyramid, isolation patterns)</li>
<li><strong>Story-Level Test Task Pattern:</strong> All tests consolidated in final Story task (NOT scattered across implementation tasks)</li>
<li><strong>Framework Detection:</strong> Auto-discovers test framework from package.json/requirements.txt/go.mod</li>
<li><strong>Structure Auto-Discovery:</strong> Scans tests/ directory for e2e/integration/unit, detects naming conventions</li>
<li><strong>Idempotent:</strong> Checks file existence, preserves existing files, re-validates on each run</li>
</ul>
</div>
<footer>
<p>Generated for ln-116-test-docs-creator skill | Version 7.0.0</p>
<p>Diagram format: Mermaid.js | Last updated: 2025-11-18</p>
</footer>
</div>
<script>
mermaid.initialize({
startOnLoad: true,
theme: 'default',
flowchart: {
useMaxWidth: true,
htmlLabels: true,
curve: 'basis'
}
});
</script>
</body>
</html>

235
skills/ln-116-test-docs-creator/references/questions.md Normal file
View File

@@ -0,0 +1,235 @@
# Test Documentation Questions
**Purpose:** Define what each section of test documentation should answer.
**Format:** Question → Expected Content → Validation Heuristics → Auto-Discovery Hints → MCP Ref Hints
---
## Table of Contents
| Document | Questions | Auto-Discovery | Priority | Line |
|----------|-----------|----------------|----------|------|
| [docs/reference/guides/testing-strategy.md](#docsreferenceguidestesting-strategymd) | 2 | None | High | L25 |
| [tests/README.md](#testsreadmemd) | 2 | High | High | L101 |
**Priority Legend:**
- **Critical:** Must answer all questions
- **High:** Strongly recommended
- **Medium:** Optional (can use template defaults)
**Auto-Discovery Legend:**
- **None:** No auto-discovery needed (use template as-is)
- **Low:** 1-2 questions need auto-discovery
- **High:** All questions need auto-discovery
---
<!-- DOCUMENT_START: docs/reference/guides/testing-strategy.md -->
## docs/reference/guides/testing-strategy.md
**File:** docs/reference/guides/testing-strategy.md (universal testing philosophy)
**Target Sections:** Testing Philosophy, Test Levels
**Rules for this document:**
- Universal testing philosophy (NOT framework-specific)
- Risk-Based Testing principle
- Story-Level Test Task Pattern
- No auto-discovery needed (standard best practices)
---
<!-- QUESTION_START: 1 -->
### Question 1: What is the overall testing approach?
**Expected Answer:** Risk-Based Testing principle, test pyramid levels (E2E/Integration/Unit), priority-driven approach (Priority ≥15)
**Target Section:** ## Testing Philosophy
**Validation Heuristics:**
- ✅ Mentions "Risk-Based Testing" or "risk-based"
- ✅ Has test pyramid description (E2E, Integration, Unit)
- ✅ Mentions priority threshold (≥15 or "Priority 15")
- ✅ References "Story-Level Test Task Pattern"
- ✅ Length > 100 words
**Auto-Discovery:**
- N/A (standard philosophy from template)
**MCP Ref Hints:**
- Research: "risk-based testing best practices" (if template needs enhancement)
- Research: "test pyramid Martin Fowler" (if need to explain pyramid rationale)
<!-- QUESTION_END: 1 -->
---
<!-- QUESTION_START: 2 -->
### Question 2: What are the test level targets?
**Expected Answer:** E2E tests 2-5 per Story, Integration tests 3-8 per Story, Unit tests 5-15 per Story, rationale for each level
**Target Section:** ## Test Levels
**Validation Heuristics:**
- ✅ Lists 3 levels: E2E, Integration, Unit
- ✅ Has numeric ranges: "2-5" for E2E, "3-8" for Integration, "5-15" for Unit
- ✅ Explains purpose/rationale for each level
- ✅ Total mentions "10-28 tests per Story"
- ✅ Length > 150 words
**Auto-Discovery:**
- N/A (standard targets from template)
**MCP Ref Hints:**
- Research: "testing pyramid ratios" (if need to justify ranges)
- Research: "value-based testing approach" (if need to explain priority-driven testing)
<!-- QUESTION_END: 2 -->
---
**Overall File Validation:**
- ✅ Has SCOPE tags in first 5 lines
- ✅ NO framework-specific code examples (FastAPI, pytest, Jest, etc.)
- ✅ Has Maintenance section at end
- ✅ Total length > 400 words
<!-- DOCUMENT_END: docs/reference/guides/testing-strategy.md -->
---
<!-- DOCUMENT_START: tests/README.md -->
## tests/README.md
**File:** tests/README.md (test organization structure)
**Target Sections:** Test Organization, Running Tests
**Rules for this document:**
- Project-specific test organization
- Auto-discovery of test frameworks (Jest/Vitest/Pytest/Mocha)
- Auto-discovery of directory structure (e2e/, integration/, unit/)
- Auto-discovery of naming conventions
- Auto-discovery of test runner commands
---
<!-- QUESTION_START: 3 -->
### Question 3: How are tests organized in this project?
**Expected Answer:** Directory structure (tests/e2e/, tests/integration/, tests/unit/), naming conventions (*.test.js or *.spec.js or test_*.py), Story-Level Test Task Pattern
**Target Section:** ## Test Organization
**Validation Heuristics:**
- ✅ Describes directory structure with 3 levels (e2e, integration, unit)
- ✅ Mentions naming conventions (*.test.*, *.spec.*, test_*.*)
- ✅ References Story-Level Test Task Pattern
- ✅ Has test framework mention (Jest, Vitest, Pytest, Mocha, etc.)
- ✅ Length > 80 words
**Auto-Discovery:**
1. **Scan tests/ directory:**
- Use Glob tool: `pattern: "tests/e2e/**/*.{js,ts,py,go}"`
- Use Glob tool: `pattern: "tests/integration/**/*.{js,ts,py,go}"`
- Use Glob tool: `pattern: "tests/unit/**/*.{js,ts,py,go}"`
- Count files in each directory
- Example output: "✓ Test structure: 12 E2E, 45 Integration, 78 Unit tests"
2. **Detect test framework:**
- Check package.json → "devDependencies" or "dependencies":
- Node.js: jest, vitest, mocha, ava, tap, jasmine
- Extract version
- Check requirements.txt (if exists):
- Python: pytest, nose2, unittest2
- Extract version
- Check go.mod (if exists):
- Go: testing (built-in)
- Example output: "✓ Test framework detected: jest@29.7.0"
3. **Extract naming conventions:**
- For each test file found:
- Extract filename pattern:
- *.test.js → "*.test.js" convention
- *.spec.ts → "*.spec.ts" convention
- test_*.py → "test_*.py" convention
- *_test.go → "*_test.go" convention
- Use most common pattern (majority rule)
- Example output: "✓ Naming convention: *.test.js (detected from 135 files)"
4. **If tests/ directory doesn't exist:**
- Create placeholder structure:
```
tests/
e2e/ (empty, ready for E2E tests)
integration/ (empty, ready for Integration tests)
unit/ (empty, ready for Unit tests)
```
- Log: "⚠️ Test directory structure created (will be populated during Story test task execution)"
**MCP Ref Hints:**
- Research: "[detected_framework] best practices" (e.g., "jest best practices 2024")
- Research: "[detected_framework] naming conventions" (if need to explain patterns)
<!-- QUESTION_END: 3 -->
---
<!-- QUESTION_START: 4 -->
### Question 4: How do I run tests locally?
**Expected Answer:** Test runner command (npm test, pytest, go test), run specific test files, run with coverage
**Target Section:** ## Running Tests
**Validation Heuristics:**
- ✅ Has test runner command (npm test, yarn test, pytest, go test, etc.)
- ✅ Mentions coverage (--coverage, coverage report, etc.)
- ✅ Shows how to run specific tests
- ✅ Has examples with actual commands
- ✅ Length > 50 words
**Auto-Discovery:**
1. **Extract test command from package.json:**
- Read package.json → "scripts" → "test"
- Extract command:
- "jest" → "npm test" (runs Jest)
- "vitest" → "npm test" (runs Vitest)
- "mocha" → "npm test" (runs Mocha)
- Custom script → use as-is
- Example output: "Test runner: npm test (runs jest)"
2. **Extract coverage command (if exists):**
- Check package.json → "scripts":
- "test:coverage": "jest --coverage"
- "coverage": "vitest run --coverage"
- Example output: "Coverage: npm run test:coverage"
3. **For Python projects:**
- Check for pytest.ini or pyproject.toml
- Default: "pytest" or "python -m pytest"
- Coverage: "pytest --cov=src"
4. **For Go projects:**
- Default: "go test ./..."
- Coverage: "go test -cover ./..."
5. **If no test script found:**
- Default based on detected framework:
- Jest → "npm test"
- Vitest → "npm test"
- Pytest → "pytest"
- Go → "go test ./..."
- Log: "⚠️ No test script found in package.json. Using default '[command]'."
**MCP Ref Hints:**
- N/A (framework-specific, use detected framework docs)
<!-- QUESTION_END: 4 -->
---
**Overall File Validation:**
- ✅ Has SCOPE tags in first 5 lines
- ✅ Has link to testing-strategy.md in Quick Navigation section
- ✅ Has Maintenance section at end
- ✅ Total length > 100 words
<!-- DOCUMENT_END: tests/README.md -->
---
**Version:** 1.0.0
**Last Updated:** 2025-11-18

465
skills/ln-116-test-docs-creator/references/testing_strategy_template.md Normal file
View File

@@ -0,0 +1,465 @@
# Testing Strategy
Universal testing philosophy and strategy for modern software projects: principles, organization, and best practices.
> **SCOPE:** Testing philosophy, risk-based strategy, test organization, isolation patterns, what to test. **NOT IN SCOPE:** Project structure, framework-specific patterns, CI/CD configuration, test tooling setup.
## Quick Navigation
- **Tests Organization:** [tests/README.md](../../tests/README.md) - Directory structure, Story-Level Pattern, running tests
- **Test Inventory:** [tests/unit/REGISTRY.md](../../tests/unit/REGISTRY.md), [tests/integration/REGISTRY.md](../../tests/integration/REGISTRY.md), [tests/e2e/REGISTRY.md](../../tests/e2e/REGISTRY.md)
---
## Core Philosophy
### Test YOUR Code, Not Frameworks
**Focus testing effort on YOUR business logic and integration usage.** Do not retest database constraints, ORM internals, framework validation, or third-party library mechanics.
**Rule of thumb:** If deleting your code wouldn't fail the test, you're testing someone else's code.
### Examples
| Verdict | Test Description | Rationale |
|---------|-----------------|-----------|
| ✅ **GOOD** | Custom validation logic raises exception for invalid input | Tests YOUR validation rules |
| ✅ **GOOD** | Repository query returns filtered results based on business criteria | Tests YOUR query construction |
| ✅ **GOOD** | API endpoint returns correct HTTP status for error scenarios | Tests YOUR error handling |
| ❌ **BAD** | Database enforces UNIQUE constraint on email column | Tests database, not your code |
| ❌ **BAD** | ORM model has correct column types and lengths | Tests ORM configuration, not logic |
| ❌ **BAD** | Framework validates request body matches schema | Tests framework validation |
---
## Risk-Based Testing Strategy
### Priority Matrix
**Automate only high-value scenarios** using Business Impact (1-5) × Probability (1-5).
| Priority Score | Action | Example Scenarios |
|----------------|--------|-------------------|
| **≥15** | MUST test | Payment processing, authentication, data loss scenarios |
| **10-14** | Consider testing | Edge cases with moderate impact |
| **<10** | Skip automated tests | Low-probability edge cases, framework behavior |
### Test Caps (per Story)
**Enforce caps to prevent test bloat:**
- **E2E:** 2-5 tests
- **Integration:** 3-8 tests
- **Unit:** 5-15 tests
- **Total:** 10-28 tests per Story
**Key principles:**
- **No minimum limits** - Can be 0 tests if no Priority ≥15 scenarios exist
- **No test pyramids** - Test distribution based on risk, not arbitrary ratios
- **Every test must add value** - Each test should validate unique Priority ≥15 scenario
**Exception:** ML/GPU/Hardware-dependent workloads may favor more E2E (5-10), fewer Integration (2-5), minimal Unit (1-3) because behavior is hardware-dependent and mocks lack fidelity. Same 10-28 total cap applies.
---
## Story-Level Testing Pattern
### When to Write Tests
**Consolidate ALL tests in Story's final test task** AFTER implementation + manual verification.
| Task Type | Contains Tests? | Rationale |
|-----------|----------------|-----------|
| **Implementation Tasks** | ❌ NO tests | Focus on implementation only |
| **Final Test Task** | ✅ ALL tests | Complete Story coverage after manual verification |
### Benefits
1. **Complete context** - Tests written when all code implemented
2. **No duplication** - E2E covers integration paths, no need to retest same code
3. **Better prioritization** - Manual testing identifies Priority ≥15 scenarios before automation
4. **Atomic delivery** - Story delivers working code + comprehensive tests together
### Anti-Pattern Example
| ❌ Wrong Approach | ✅ Correct Approach |
|-------------------|---------------------|
| Task 1: Implement feature X + write unit tests<br>Task 2: Update integration + write integration tests<br>Task 3: Add logging + write E2E tests | Task 1: Implement feature X<br>Task 2: Update integration points<br>Task 3: Add logging<br>**Task 4 (Final): Write ALL tests (2 E2E, 3 Integration, 8 Unit)** |
| **Result:** Tests scattered, duplication, incomplete coverage | **Result:** Tests consolidated, no duplication, complete coverage |
---
## Test Organization
### Directory Structure
```
tests/
├── e2e/ # End-to-end tests (full system, real services)
│ ├── test_user_journey.ext
│ └── REGISTRY.md # E2E test inventory
├── integration/ # Integration tests (multiple components, real dependencies)
│ ├── api/
│ ├── services/
│ ├── db/
│ └── REGISTRY.md # Integration test inventory
├── unit/ # Unit tests (single component, mocked dependencies)
│ ├── api/
│ ├── services/
│ ├── db/
│ └── REGISTRY.md # Unit test inventory
└── README.md # Test documentation
```
### Test Inventory (REGISTRY.md)
**Each test category has REGISTRY.md** with detailed test descriptions:
**Purpose:**
- Document what each test validates
- Track test counts per Epic/Story
- Provide navigation for test maintenance
**Format example:**
```markdown
# E2E Test Registry
## Quality Estimation (Epic 6 - API-69)
**File:** tests/e2e/test_quality_estimation.ext
**Tests (4):**
1. **evaluate_endpoint_batch_splitting** - MetricX batch splitting (segments >128 split into batches)
2. **evaluate_endpoint_gpu_integration** - MetricX-24 GPU service integration
3. **evaluate_endpoint_error_handling** - Service timeout handling (503 status)
4. **evaluate_endpoint_response_format** - Response schema validation
**Total:** 4 E2E tests | **Coverage:** 100% Priority ≥15 scenarios
```
---
## Test Levels
### E2E (End-to-End) Tests
**Definition:** Full system tests with real external services and complete data flow.
**Characteristics:**
- Real external APIs/services
- Real database
- Full request-response cycle
- Validates complete user journeys
**When to write:**
- Critical user workflows (authentication, payments, core features)
- Integration with external services
- Priority ≥15 scenarios that span multiple systems
**Example:** User registration flow (E2E) vs individual validation function (Unit)
### Integration Tests
**Definition:** Tests multiple components together with real dependencies (database, cache, file system).
**Characteristics:**
- Real database/cache/file system
- Multiple components interact
- May mock external APIs
- Validates component integration
**When to write:**
- Database query behavior
- Service orchestration
- Component interaction
- API endpoint behavior (without external services)
**Example:** Repository query with real database vs service logic with mocked repository
### Unit Tests
**Definition:** Tests single component in isolation with mocked dependencies.
**Characteristics:**
- Fast execution (<1ms per test)
- No external dependencies
- Mocked collaborators
- Validates single responsibility
**When to write:**
- Business logic validation
- Complex calculations
- Error handling logic
- Custom transformations
**Example:** Validation function with mocked data vs endpoint with real database
---
## Isolation Patterns
### Pattern Comparison
| Pattern | Speed | Complexity | Best For |
|---------|-------|------------|----------|
| **Data Deletion** | ⚡⚡⚡ Fastest | Simple | Default choice (90% of projects) |
| **Transaction Rollback** | ⚡⚡ Fast | Moderate | Transaction semantics testing |
| **Database Recreation** | ⚡ Slow | Simple | Maximum isolation paranoia |
### Data Deletion (Default)
**How it works:**
1. Create schema once at test session start
2. Delete data after each test
3. Drop schema at test session end
**Benefits:**
- Fast (5-8s for 50 tests)
- Simple implementation
- Full isolation between tests
**When to use:** Default choice for most projects
### Transaction Rollback
**How it works:**
1. Start transaction before each test
2. Run test code
3. Rollback transaction after test
**Benefits:**
- Good for testing transaction semantics
- Faster than DB recreation
**When to use:** Testing transaction behavior, savepoints, isolation levels
### Database Recreation
**How it works:**
1. Drop and recreate database before each test
2. Apply migrations
3. Run test
**Benefits:**
- Maximum isolation
- Catches migration issues
**When to use:** Paranoia about shared state, testing migrations
---
## What To Test vs NOT Test
### ✅ Test (GOOD)
**Test YOUR code and integration usage:**
| Category | Examples |
|----------|----------|
| **Business logic** | Validation rules, orchestration, error handling, computed properties |
| **Query construction** | Filters, joins, aggregations, pagination |
| **API behavior** | Request validation, response shape, HTTP status codes |
| **Custom validators** | Complex validation logic, transformations |
| **Integration smoke** | Database connectivity, basic CRUD, configuration |
### ❌ Avoid (BAD)
**Don't test framework internals and third-party libraries:**
| Category | Examples |
|----------|----------|
| **Database constraints** | UNIQUE, FOREIGN KEY, NOT NULL, CHECK constraints |
| **ORM internals** | Column types, table creation, metadata, relationships |
| **Framework validation** | Request body validation, dependency injection, routing |
| **Third-party libraries** | HTTP client behavior, serialization libraries, cryptography |
---
## Testing Patterns
### Arrange-Act-Assert
**Structure tests clearly:**
```
test_example:
# ARRANGE: Set up test data and dependencies
setup_data()
mock_dependencies()
# ACT: Execute code under test
result = execute_operation()
# ASSERT: Verify outcomes
assert result == expected
verify_side_effects()
```
**Benefits:**
- Clear test structure
- Easy to read and maintain
- Explicit test phases
### Mock at the Seam
**Mock at component boundaries, not internals:**
| Test Type | What to Mock | What to Use Real |
|-----------|--------------|------------------|
| **Unit tests** | External dependencies (repositories, APIs, file system) | Business logic |
| **Integration tests** | External APIs, slow services | Database, cache, your code |
| **E2E tests** | Nothing (or minimal external services) | Everything |
**Anti-pattern:** Over-mocking your own code defeats the purpose of integration tests.
### Test Data Builders
**Create readable test data:**
```
# Builder pattern for test data
user = build_user(
email="test@example.com",
role="admin",
active=True
)
# Easy to create edge cases
inactive_user = build_user(active=False)
guest_user = build_user(role="guest")
```
**Benefits:**
- Readable test setup
- Easy edge case creation
- Reusable across tests
---
## Common Issues
### Flaky Tests
**Symptom:** Tests pass/fail randomly without code changes
**Common causes:**
- Shared state between tests (global variables, cached data)
- Time-dependent logic (timestamps, delays)
- External service instability
- Improper cleanup between tests
**Solutions:**
- Isolate test data (per-test creation, cleanup)
- Mock time-dependent code
- Use test-specific configurations
- Implement proper teardown
### Slow Tests
**Symptom:** Test suite takes too long (>30s for 50 tests)
**Common causes:**
- Database recreation per test
- Running migrations per test
- No connection pooling
- Too many E2E tests
**Solutions:**
- Use Data Deletion pattern
- Run migrations once per session
- Optimize test data creation
- Balance test levels (more Unit, fewer E2E)
### Test Coupling
**Symptom:** Changing one component breaks many unrelated tests
**Common causes:**
- Tests depend on implementation details
- Shared test fixtures across unrelated tests
- Testing framework internals instead of behavior
**Solutions:**
- Test behavior, not implementation
- Use independent test data per test
- Focus on public APIs, not internal state
---
## Coverage Guidelines
### Targets
| Layer | Target | Priority |
|-------|--------|----------|
| **Critical business logic** | 100% branch coverage | HIGH |
| **Repositories/Data access** | 90%+ line coverage | HIGH |
| **API endpoints** | 80%+ line coverage | MEDIUM |
| **Utilities/Helpers** | 80%+ line coverage | MEDIUM |
| **Overall** | 80%+ line coverage | MEDIUM |
### What Coverage Means
**Coverage is a tool, not a goal:**
- ✅ High coverage + focused tests = good quality signal
- ❌ High coverage + meaningless tests = false confidence
- ❌ Low coverage = blind spots in testing
**Focus on:**
- Critical paths covered
- Edge cases tested
- Error handling validated
**Not on:**
- Arbitrary percentage targets
- Testing getters/setters
- Framework code
---
## Verification Checklist
### Strategy
- [ ] Risk-based selection (Priority ≥15)
- [ ] Test caps enforced (E2E 2-5, Integration 3-8, Unit 5-15)
- [ ] Total 10-28 tests per Story
- [ ] Tests target YOUR code, not framework internals
- [ ] E2E smoke tests for critical integrations
### Organization
- [ ] Story-Level Test Task Pattern followed
- [ ] Tests consolidated in final Story task
- [ ] REGISTRY.md files maintained for all test categories
- [ ] Test directory structure follows conventions
### Isolation
- [ ] Isolation pattern chosen (Data Deletion recommended)
- [ ] Each test creates own data
- [ ] Proper cleanup between tests
- [ ] No shared state between tests
### Quality
- [ ] Tests are order-independent
- [ ] Tests run fast (<10s for 50 integration tests)
- [ ] No flaky tests
- [ ] Coverage ≥80% overall, 100% for critical logic
- [ ] Meaningful test names and descriptions
---
## Maintenance
**Update Triggers:**
- New testing patterns discovered
- Framework version changes affecting tests
- Significant changes to test architecture
- New isolation issues identified
**Verification:** Review this strategy when starting new projects or experiencing test quality issues.
**Last Updated:** [CURRENT_DATE] - Initial universal testing strategy

114
skills/ln-116-test-docs-creator/references/tests_readme_template.md Normal file
View File

@@ -0,0 +1,114 @@
# Test Documentation
**Last Updated:** {{DATE}}
<!-- SCOPE: Test organization structure and Story-Level Test Task Pattern ONLY. Contains test directories organization, test execution commands, quick navigation. -->
<!-- DO NOT add here: Test code → Test files, Story implementation → docs/tasks/kanban_board.md, Test strategy → Story test task descriptions -->
---
## Overview
This directory contains all tests for the project, following the **Story-Level Test Task Pattern** where tests are consolidated in the final Story test task (NOT scattered across implementation tasks).
**Test organization:**
- **E2E tests** (End-to-End) - 2-5 per Story - Priority ≥15 scenarios MUST be tested
- **Integration tests** - 3-8 per Story - Multi-component interactions
- **Unit tests** - 5-15 per Story - Individual component logic
- **Total**: 10-28 tests per Story (Value-Based Testing)
---
## Testing Philosophy
**Test YOUR code, not frameworks.** Focus on business logic and integration usage. Avoid testing database constraints, ORM internals, or framework validation.
**Risk-based testing:** Automate only Priority ≥15 scenarios (Business Impact × Probability). Test caps prevent bloat: 2-5 E2E, 3-8 Integration, 5-15 Unit (10-28 total per Story). No minimum limits - can be 0 if no high-priority scenarios exist.
**Rule of thumb:** If deleting your code wouldn't fail the test, you're testing someone else's code.
👉 **Full strategy:** See [docs/reference/guides/testing-strategy.md](../docs/reference/guides/testing-strategy.md)
---
## Test Structure
```
tests/
├── e2e/ # End-to-End tests (2-5 per Story)
│ ├── auth/
│ ├── user-flows/
│ └── critical-paths/
├── integration/ # Integration tests (3-8 per Story)
│ ├── api/
│ ├── database/
│ └── services/
└── unit/ # Unit tests (5-15 per Story)
├── components/
├── utils/
└── services/
```
---
## Story-Level Test Task Pattern
**Rule**: All tests (E2E/Integration/Unit) are written in the **final Story test task** (created by ln-350-story-test-planner after manual testing).
**Why**:
- **Single source of truth**: All Story tests in one place
- **Atomic completion**: Story Done when all tests pass
- **No scattered tests**: NOT in implementation tasks
- **Regression prevention**: Test suite runs before Story marked Done
**Workflow**:
1. Implementation tasks completed → Manual testing → Bugs fixed
2. ln-350-story-test-planner creates Story Finalizer test task
3. ln-334-test-executor implements all tests (E2E/Integration/Unit) in final task
4. All tests pass → Story marked Done
---
## Test Execution
**Run all tests:**
```bash
npm test
```
**Run specific test suites:**
```bash
npm run test:unit # Unit tests only
npm run test:integration # Integration tests only
npm run test:e2e # E2E tests only
```
**Watch mode (development):**
```bash
npm run test:watch
```
---
## Quick Navigation
- **Testing Strategy**: [docs/reference/guides/testing-strategy.md](../docs/reference/guides/testing-strategy.md) - Philosophy, risk-based strategy, what to test
- **Story test tasks**: [docs/tasks/kanban_board.md](../docs/tasks/kanban_board.md) - Story test task tracking
- **Story-Level Pattern**: [docs/tasks/README.md](../docs/tasks/README.md) - Full pattern explanation
- **Test guidelines**: [docs/reference/guides/](../docs/reference/guides/) - Additional testing best practices
---
## Maintenance
**Update Triggers**:
- When adding new test directories or test suites
- When changing test execution commands
- When modifying Story-Level Test Task Pattern workflow
**Verification**:
- All test directories exist (e2e/, integration/, unit/)
- Test execution commands work correctly
- SCOPE tags correctly define test documentation boundaries
**Last Updated**: {{DATE}}

385
skills/ln-200-scope-decomposer/SKILL.md Normal file
View File

@@ -0,0 +1,385 @@
---
name: ln-200-scope-decomposer
description: Orchestrates full decomposition (scope → Epics → Stories) by delegating ln-210 → ln-220. Sequential Story decomposition per Epic. Epic 0 for Infrastructure.
---
# Scope Decomposer (Top Orchestrator)
Top-level orchestrator for complete initiative decomposition from scope to User Stories through Epic and Story coordinators.
## Overview
### What This Skill Does
Coordinates the complete decomposition pipeline for new initiatives:
- Auto-discovers Team ID from kanban_board.md
- **Phase 1:** Discovery (Team ID)
- **Phase 2:** Epic Decomposition (delegates to ln-210-epic-coordinator)
- **Phase 3:** Story Decomposition Loop (delegates to ln-220-story-coordinator per Epic, sequential)
- **Phase 4:** Summary (total counts + next steps)
### When to Use This Skill
This skill should be used when:
- Start new initiative requiring full decomposition (scope → Epics → Stories)
- Automate Epic + Story creation in single workflow
- Prefer full pipeline over manual step-by-step invocation
- Time-efficient approach for new projects (2-3 hours end-to-end)
**Alternative:** For granular control, invoke coordinators manually:
1. [ln-210-epic-coordinator](../ln-210-epic-coordinator/SKILL.md) - CREATE/REPLAN Epics
2. [ln-220-story-coordinator](../ln-220-story-coordinator/SKILL.md) - CREATE/REPLAN Stories (once per Epic)
### When NOT to Use
Do NOT use if:
- Initiative already has Epics → Use ln-210-epic-coordinator REPLAN mode instead
- Need to replan existing Stories → Use ln-220-story-coordinator REPLAN mode per Epic
- Only need Epic creation → Use ln-210-epic-coordinator directly
- Only need Story creation for specific Epic → Use ln-220-story-coordinator directly
---
## Core Concepts
### Orchestrator Pattern
**ln-200-scope-decomposer is a pure coordinator** - it does NOT execute work directly:
- ✅ Discovers context (Team ID)
- ✅ Makes routing decisions (which coordinator to invoke)
- ✅ Delegates all work via Skill tool (ln-210, ln-220)
- ✅ Manages workflow state (Epic creation → Story loop)
- ❌ Does NOT research project docs (ln-210 does this)
- ❌ Does NOT generate Epic/Story documents (ln-210/ln-220 do this)
- ❌ Does NOT create Linear issues (coordinators do this)
- ❌ Does NOT prompt user (coordinators handle all user interaction)
**Coordinators:**
- **ln-210-epic-coordinator:** Creates 3-7 Epics (Epic 0 for Infrastructure if applicable, Epic 1-N for business domains)
- **ln-220-story-coordinator:** Creates 5-10 Stories per Epic (with standards research via ln-221)
### Sequential Story Decomposition
**CRITICAL CONSTRAINT:** Epic N Stories MUST complete before Epic N+1 starts.
**Why sequential?**
- ln-220-story-coordinator includes user interaction (Story preview confirmation)
- Interactive dialog cannot be parallelized (user must review each Epic's Stories)
- Ensures Epic N Stories are approved and created before starting Epic N+1
**Example:** 6 Epics → ln-220 invoked 6 times sequentially (Epic 0 → Epic 1 → Epic 2 → ... → Epic 5)
### Infrastructure Epic = Epic 0
**Reserved number:** Epic 0 is reserved for Infrastructure Epic (if proposed by ln-210).
**Numbering:**
- IF Infrastructure Epic exists → Epic 0 (Infrastructure), Epic 1-N (business domains)
- ELSE → Epic 1-N (business domains only)
**Decision:** ln-210-epic-coordinator Phase 1 Step 3 automatically determines if Infrastructure Epic is needed (new project, multi-stack, security/monitoring requirements).
### Auto-Discovery
**Team ID**: Auto-discovered from `docs/tasks/kanban_board.md` Linear Configuration table (see CLAUDE.md "Configuration Auto-Discovery").
**Fallback:** If kanban_board.md missing → ln-210-epic-coordinator will ask user directly
---
## Workflow
### Phase 1: Discovery (Automated)
Auto-discovers Team ID from `docs/tasks/kanban_board.md`.
**Validation:**
- Team ID exists in kanban_board.md
- If missing → Skip (ln-210 will request from user)
**NO user confirmation at orchestrator level** - coordinators handle all user interaction.
**Output:** Team ID (or None if not found)
### Phase 2: Epic Decomposition (Delegated)
**Objective:** Create all Epics for initiative.
Delegate to ln-210-epic-coordinator:
```
🔄 [ORCHESTRATOR] Phase 2: Delegating Epic creation to ln-210-epic-coordinator
Skill(skill: "ln-210-epic-coordinator")
```
**ln-210-epic-coordinator will:**
- Phase 1: Research project docs (requirements.md, architecture.md, tech_stack.md)
- Phase 2: Auto-propose domains + Infrastructure Epic (Epic 0) → User confirms domain list
- Phase 3: Build IDEAL Epic plan (Epic 0-N)
- Phase 5a: Auto-extract Q1-Q4 from docs → Generate ALL Epic documents → Show batch preview → User confirms → Create all Epics
- Return: Epic URLs + summary
**After completion:** Epics created in Linear, kanban_board.md updated.
**Output:** 3-7 Epics created (Epic 0 for Infrastructure if applicable, Epic 1-N for business domains)
### Phase 3: Story Decomposition Loop (Sequential, Delegated)
**Objective:** Create Stories for EACH Epic (sequential processing).
**Sequential Loop Logic:**
```
FOR EACH Epic (Epic 0, Epic 1, ..., Epic N):
1. Invoke ln-220-story-coordinator for current Epic
2. Wait for completion
3. Verify Stories created in kanban_board.md
4. Move to next Epic
```
**Invocation per Epic:**
```
🔄 [ORCHESTRATOR] Phase 3: Delegating Story creation for Epic N to ln-220-story-coordinator
Skill(skill: "ln-220-story-coordinator", epic_number="Epic N")
```
**ln-220-story-coordinator will (per Epic):**
- Phase 1: Auto-extract Q1-Q6 from Epic + Fallback search (requirements.md, tech_stack.md)
- Phase 2: Research standards via ln-221-standards-researcher (auto)
- Phase 3: Build IDEAL Story plan (5-10 Stories)
- Phase 4a: Generate ALL Story documents → Show preview → User confirms → Create all Stories
- Return: Story URLs + summary
**Sequential constraint explanation:**
- ln-220 includes user interaction (Story preview confirmation)
- Cannot parallelize - user must review each Epic's Stories sequentially
- Epic N Stories approved → Epic N+1 Stories generated
**After each Epic:** Stories created in Linear, kanban_board.md updated.
**Output:** 30-60 Stories total (5-10 per Epic × 3-7 Epics)
### Phase 4: Summary and Next Steps
**Objective:** Provide complete decomposition overview.
```
🔄 [ORCHESTRATOR] Phase 4: Full decomposition complete
Initiative Decomposition Summary:
- Epics created: N Projects (Epic 0: Infrastructure [if exists], Epic 1-N: Business domains)
- Stories created: M Issues (breakdown per Epic)
- Location: docs/tasks/kanban_board.md
Next Steps:
1. Run ln-320-story-validator to validate all Stories
2. Use ln-300-story-pipeline to process each Story (tasks → execution → Done)
OR use ln-310-story-decomposer to create tasks manually for each Story
```
**Output:** Summary message with full decomposition results
---
## Critical Rules
### 1. Pure Orchestrator Pattern
**Orchestrator responsibilities:**
- ✅ Discovery (Team ID)
- ✅ Routing decisions (which coordinator to invoke, when)
- ✅ Sequential loop management (Epic 0 → Epic 1 → ... → Epic N)
- ✅ Summary aggregation (count Epics, Stories)
**Coordinator responsibilities** (NOT orchestrator):
- ❌ Research project docs → ln-210
- ❌ Auto-extract Epic/Story info → ln-210/ln-220
- ❌ Generate Epic/Story documents → ln-210/ln-220
- ❌ Create Linear issues → ln-210/ln-220
- ❌ User interaction (confirmations) → ln-210/ln-220
### 2. Sequential Story Decomposition
**HARD RULE:** Epic N Stories MUST complete before Epic N+1 starts.
**Rationale:** ln-220 includes user interaction (Story preview confirmation). Interactive dialog cannot be parallelized.
**Example:** 6 Epics → 6 sequential ln-220 invocations (Epic 0 → Epic 1 → ... → Epic 5)
### 3. No User Prompts at Orchestrator Level
**Orchestrator does NOT prompt user:**
- ❌ NO "Proceed with decomposition?" confirmation (redundant - coordinators already confirm)
- ❌ NO time estimates (misleading - actual time varies)
- ❌ NO Epic/Story previews (coordinators handle this)
**All user interaction delegated to coordinators:**
- ln-210 Phase 2: Domain approval (USER CONTROL POINT 1)
- ln-210 Phase 5a: Epic batch preview (USER CONTROL POINT 2)
- ln-220 Phase 4a: Story preview per Epic (USER CONTROL POINT 3, N times)
### 4. Epic 0 for Infrastructure
**Reserved number:** Epic 0 is reserved for Infrastructure Epic.
**Decision point:** ln-210-epic-coordinator Phase 1 Step 3 automatically determines if Infrastructure Epic needed.
**Numbering:** Epic 0 (if Infrastructure), Epic 1-N (business domains)
---
## Definition of Done
Before completing work, verify ALL checkpoints:
**✅ Team ID Discovered (Phase 1):**
- [ ] Team ID loaded from kanban_board.md OR skipped (ln-210 will request)
**✅ Epic Decomposition Complete (Phase 2):**
- [ ] Delegated to ln-210-epic-coordinator
- [ ] 3-7 Epics created (Epic 0 for Infrastructure if applicable, Epic 1-N for business domains)
- [ ] Epic URLs returned
- [ ] Epics visible in kanban_board.md
**✅ Story Decomposition Complete (Phase 3):**
- [ ] Delegated to ln-220-story-coordinator for EACH Epic (sequential)
- [ ] 5-10 Stories created per Epic
- [ ] Story URLs returned for each Epic
- [ ] All Stories visible in kanban_board.md (Backlog section)
**✅ Summary Provided (Phase 4):**
- [ ] Total counts displayed (Epics, Stories, breakdown per Epic)
- [ ] kanban_board.md location shown
- [ ] Next steps provided (validation, task creation)
**Output:** Summary message with full decomposition results (Epics + Stories per Epic)
---
## Integration with Ecosystem
### Called By
Users directly: "Decompose initiative: [initiative name]" or "Create epics and stories for [project]"
### Calls (via Skill tool)
- **ln-210-epic-coordinator** (Phase 2) - CREATE mode (batch Epic creation with batch preview)
- **ln-220-story-coordinator** (Phase 3, sequential loop) - CREATE mode per Epic (Story creation with preview)
### Downstream
After ln-200-scope-decomposer completes:
- **ln-320-story-validator** - validates all created Stories before task creation
- **ln-300-story-pipeline** - processes each Story (tasks → execution → Done)
- OR **ln-310-story-decomposer** - creates tasks manually for each Story
---
## Best Practices
### Orchestrator Responsibilities
**DO:**
- ✅ Auto-discover Team ID
- ✅ Delegate to coordinators
- ✅ Manage sequential loop (Epic 0 → Epic 1 → ... → Epic N)
- ✅ Aggregate summary (count Epics, Stories)
**DON'T:**
- ❌ Research project docs (ln-210 does this)
- ❌ Generate documents (coordinators do this)
- ❌ Create Linear issues (coordinators do this)
- ❌ Prompt user (coordinators handle all interaction)
### Coordinator Trust
**Trust coordinator results:** Coordinators return summary, orchestrator doesn't re-verify.
**Error handling:** If coordinator returns error, report to user and stop pipeline.
### Sequential Processing
**Epic creation first:** Phase 2 creates ALL Epics before Phase 3 starts (ensures Epic IDs available).
**Story creation sequential:** Phase 3 processes Epics one-by-one (Epic N Stories → Epic N+1 Stories).
**Rationale:** User interaction in ln-220 requires sequential processing (cannot parallelize confirmations).
### Time Estimates
**Realistic estimate:** 2-3 hours for full decomposition (6 Epics × 7 Stories avg = 42 Stories).
**Breakdown:**
- Phase 2 (Epic creation): 30-45 min (batch preview reduces time)
- Phase 3 (Story creation): 1.5-2 hours (6 Epics × 15-20 min per Epic)
- Phase 4 (Summary): 2 min
**Do NOT provide time estimates to user** - varies based on project complexity and user response time.
---
## Example Usage
**Request:**
```
"Decompose initiative: E-commerce Platform"
```
**Execution:**
1. **Phase 1: Discovery**
- Team ID loaded from kanban_board.md
2. **Phase 2: Epic Decomposition**
- Invoke ln-210-epic-coordinator
- ln-210 creates 6 Epics:
- Epic 11 (Infrastructure Epic 0 pattern)
- Epic 12-16 (business domains)
- Output: 6 Epic URLs
3. **Phase 3: Story Decomposition Loop (Sequential)**
- **Epic 11:** Invoke ln-220 → 6 Stories (US017-US022)
- **Epic 12:** Invoke ln-220 → 7 Stories (US023-US029)
- **Epic 13:** Invoke ln-220 → 5 Stories (US030-US034)
- **Epic 14:** Invoke ln-220 → 6 Stories (US035-US040)
- **Epic 15:** Invoke ln-220 → 7 Stories (US041-US047)
- **Epic 16:** Invoke ln-220 → 5 Stories (US048-US052)
- Output: 36 Stories total
4. **Phase 4: Summary**
```
🔄 [ORCHESTRATOR] Full decomposition complete
Initiative: E-commerce Platform
- Epics created: 6 Projects (Epic 11: Infrastructure, Epic 12-16: Business domains)
- Stories created: 36 Issues
- Epic 11: 6 Stories
- Epic 12: 7 Stories
- Epic 13: 5 Stories
- Epic 14: 6 Stories
- Epic 15: 7 Stories
- Epic 16: 5 Stories
- Location: docs/tasks/kanban_board.md
Next Steps:
1. Run ln-320-story-validator to validate all Stories
2. Use ln-300-story-pipeline to process each Story (tasks → execution → Done)
```
**Result:** 6 Epics + 36 Stories created through full pipeline automation
---
## Chat Output Prefix
Use emoji prefix for visual differentiation:
- 🔄 [ORCHESTRATOR] - ln-200-scope-decomposer (top orchestrator)
**Purpose:** Helps users track orchestrator progress when delegating to multiple coordinators.
---
**Version:** 2.0.0 (BREAKING: Complete rewrite following ln-300 Pure Orchestrator Pattern. Removed Phase 1 User Confirmation. Removed false "AUTOMATIC" claims. Added Epic 0 for Infrastructure. Added Sequential Story Decomposition explanation. Added Critical Rules section. Realistic time estimates (2-3h). Removed REPLAN mode (not applicable to top orchestrator - use ln-210/ln-220 REPLAN modes instead).)
**Last Updated:** 2025-11-20

151
skills/ln-200-scope-decomposer/diagram.html Normal file
View File

@@ -0,0 +1,151 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>ln-200-scope-decomposer - State Diagram</title>
<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
<link rel="stylesheet" href="../shared/css/diagram.css">
</head>
<body>
<div class="container">
<header>
<h1>🔄 ln-200-scope-decomposer</h1>
<p class="subtitle">Scope Decomposer (Top Orchestrator) - State Diagram v2.0.0</p>
</header>
<div class="info-box">
<h3>📋 Workflow Overview</h3>
<ul>
<li><strong>Purpose:</strong> Full decomposition: scope → Epics (ln-210) → Stories (ln-220 loop)</li>
<li><strong>Pattern:</strong> Pure Orchestrator (only routing, no work execution)</li>
<li><strong>Delegation:</strong> ln-210-epic-coordinator v7.0.0 → ln-220-story-coordinator v4.0.0 (sequential per Epic)</li>
<li><strong>Output:</strong> 3-7 Epics (Epic 0: Infrastructure, Epic 1-N: Business) + 15-70 Stories (5-10 per Epic)</li>
<li><strong>Time:</strong> 2-3 hours end-to-end</li>
</ul>
</div>
<div class="legend">
<div class="legend-item">
<div class="legend-color color-discovery"></div>
<span>Discovery</span>
</div>
<div class="legend-item">
<div class="legend-color color-loop"></div>
<span>Delegation</span>
</div>
<div class="legend-item">
<div class="legend-color color-decision"></div>
<span>Loop Control</span>
</div>
<div class="legend-item">
<div class="legend-color color-action"></div>
<span>Completion</span>
</div>
</div>
<div class="diagram-container">
<div class="mermaid">
graph TD
Start([Start: Decompose Initiative]) --> Phase1[Phase 1: Discovery<br/>Auto-discover Team ID<br/>from kanban_board.md]
Phase1 --> Phase2[Phase 2: Epic Decomposition<br/>Delegate to ln-210-epic-coordinator v7.0.0]
Phase2 --> LN210[ln-210 executes:<br/>- Research docs + HTML<br/>- Build Epic list Epic 0-N<br/>- User confirms structure<br/>- Batch preview ALL Epics<br/>- User confirms<br/>- Create ALL in Linear]
LN210 --> WaitEpics[Wait for Epic creation complete]
WaitEpics --> VerifyEpics[Verify: Epics in kanban_board.md<br/>Epic 0: Infrastructure if applicable<br/>Epic 1-N: Business domains]
VerifyEpics --> Phase3[Phase 3: Story Decomposition Loop<br/>Sequential per Epic]
Phase3 --> LoopStart[FOR EACH Epic<br/>Epic 0 → Epic 1 → ... → Epic N]
LoopStart --> CurrentEpic[Current Epic: Epic X]
CurrentEpic --> DelegateLN220[Delegate to ln-220-story-coordinator<br/>for Epic X]
DelegateLN220 --> LN220[ln-220 executes:<br/>- Extract Epic info<br/>- Fallback search if needed<br/>- Research standards<br/>- Generate Stories<br/>- User confirms<br/>- Create in Linear]
LN220 --> WaitStories[Wait for Story creation complete]
WaitStories --> VerifyStories[Verify: Stories in kanban_board.md<br/>5-10 Stories for Epic X]
VerifyStories --> MoreEpics{More Epics<br/>to process?}
MoreEpics -->|Yes| LoopStart
MoreEpics -->|No| Phase4[Phase 4: Summary]
Phase4 --> CountTotal[Count total:<br/>N Epics Epic 0-N<br/>M Stories US001-USMMM]
CountTotal --> ShowNext[Display next steps:<br/>1. ln-320-story-validator<br/>2. ln-300-story-pipeline<br/>OR ln-310-story-decomposer]
ShowNext --> End([End: Full Decomposition Complete])
%% Styling
classDef discovery fill:#E3F2FD,stroke:#1976D2,stroke-width:2px
classDef loop fill:#FFF9C4,stroke:#F57C00,stroke-width:2px
classDef decision fill:#FFE0B2,stroke:#E64A19,stroke-width:2px
classDef action fill:#C8E6C9,stroke:#388E3C,stroke-width:2px
class Phase1 discovery
class Phase2,Phase3,LN210,LN220,DelegateLN220,CurrentEpic,LoopStart loop
class MoreEpics decision
class WaitEpics,VerifyEpics,WaitStories,VerifyStories,Phase4,CountTotal,ShowNext action
</div>
</div>
<div class="info-box">
<h3>🔑 Key Features v2.0.0</h3>
<ul>
<li><strong>Pure Orchestrator Pattern:</strong> Does NOT execute work - only routing via Skill tool</li>
<li><strong>NO Orchestrator-Level Confirmation:</strong> Coordinators (ln-210, ln-220) handle all user interaction</li>
<li><strong>Epic 0 Reserved:</strong> Infrastructure Epic automatically proposed by ln-210 if needed</li>
<li><strong>Sequential Story Decomposition:</strong> Epic N Stories MUST complete before Epic N+1 starts (user interaction cannot parallelize)</li>
<li><strong>Batch Preview in ln-210:</strong> ALL Epics shown before creation (v7.0.0 feature)</li>
<li><strong>Fallback Search in ln-220:</strong> Auto-extract from requirements.md, tech_stack.md before asking user (v2.1.0 feature)</li>
</ul>
</div>
<div class="info-box">
<h3>📐 Phase Structure</h3>
<ul>
<li><strong>Phase 1:</strong> Discovery - Auto-discover Team ID from kanban_board.md (silent, no user prompt)</li>
<li><strong>Phase 2:</strong> Epic Decomposition - Delegate to ln-210-epic-coordinator v7.0.0 (batch preview, Epic 0 if applicable)</li>
<li><strong>Phase 3:</strong> Story Decomposition Loop - FOR EACH Epic (Epic 0 → Epic 1 → ... → Epic N), delegate to ln-220-story-coordinator v4.0.0 sequentially</li>
<li><strong>Phase 4:</strong> Summary - Count total Epics + Stories, display next steps (validation → task creation)</li>
</ul>
</div>
<div class="info-box">
<h3>⚙️ Orchestrator Responsibilities</h3>
<ul>
<li><strong>✅ DOES:</strong> Discovery (Team ID), Routing decisions, Sequential loop management, Summary aggregation</li>
<li><strong>❌ DOES NOT:</strong> Research docs, Generate documents, Create Linear issues, Prompt user (delegated to coordinators)</li>
</ul>
</div>
<div class="info-box">
<h3>🔗 Coordinator Details</h3>
<ul>
<li><strong>ln-210-epic-coordinator v7.0.0:</strong> Creates 3-7 Epics (Epic 0 Infrastructure + Epic 1-N Business). Batch preview ALL before creation. HTML research. User confirms twice (structure + batch preview).</li>
<li><strong>ln-220-story-coordinator v4.0.0:</strong> Coordinator that delegates to ln-222-story-creator (CREATE mode) or ln-223-story-replanner (REPLAN mode). Creates 5-10 Stories per Epic. Fallback search chain (Epic → requirements.md → tech_stack.md). User confirms once (Story preview).</li>
</ul>
</div>
<footer>
<p>Generated for ln-200-scope-decomposer skill | Version 2.0.0</p>
<p>Diagram format: Mermaid.js | Last updated: 2025-11-20</p>
</footer>
</div>
<script>
mermaid.initialize({
startOnLoad: true,
theme: 'default',
flowchart: {
useMaxWidth: true,
htmlLabels: true,
curve: 'basis'
}
});
</script>
</body>
</html>

594
skills/ln-210-epic-coordinator/SKILL.md Normal file
View File

@@ -0,0 +1,594 @@
---
name: ln-210-epic-coordinator
description: CREATE/REPLAN Epics from scope (3-7 Epics). Batch Preview + Auto-extraction. Decompose-First Pattern. Auto-discovers team ID.
---
# Epic Coordinator
Universal Epic management coordinator that handles both creation and replanning through scope decomposition.
## When to Use This Skill
This skill should be used when:
- Start new scope/initiative requiring decomposition into multiple logical domains (CREATE mode)
- Break down large architectural requirement into Epics
- Update existing Epics when scope/requirements change (REPLAN mode)
- Rebalance Epic scopes within an initiative
- Add new Epics to existing initiative structure
- First step in project planning (scope → Epics → Stories → Tasks)
- Define clear scope boundaries and success criteria for each domain
**Output:** 3-7 Linear Projects (logical domains/modules)
## Core Concepts
### Decompose-First Pattern
**Key principle:** ALWAYS analyze scope and build IDEAL Epic plan FIRST, THEN check existing Epics to determine mode:
- **No existing Epics** → CREATE MODE (generate and create all Epics)
- **Has existing Epics** → REPLAN MODE (compare, determine operations: KEEP/UPDATE/OBSOLETE/CREATE)
**Rationale:** Ensures consistent Epic decomposition based on current scope requirements, independent of existing Epic structure (which may be outdated or suboptimal).
### Epic 0 Reserved for Infrastructure
**Rule:** Epic 0 is a reserved index for Infrastructure Epic within an initiative.
**When to use Epic 0:**
- New project requiring infrastructure setup
- Multi-stack project (Frontend + Backend on different stacks)
- Project with security/monitoring/deployment requirements
**Epic indexes within initiative:**
- **Epic 0:** Infrastructure & Operations (if needed)
- **Epic 1, 2, 3, ... N:** Business domains
**Linear Project Titles:**
- Use Next Epic Number from kanban_board.md for sequential numbering
- Example: Next Epic Number = 11
- Epic 0 → Linear title: "Epic 11: Infrastructure & Operations"
- Epic 1 → Linear title: "Epic 12: User Management"
- Epic 2 → Linear title: "Epic 13: Product Catalog"
**Important:** Epic 0/1/2 are initiative-internal indexes for organizing domains. Linear uses global Next Epic Number for project titles.
---
## Workflow
### Phase 1: Discovery & Research
**Objective:** Gather all necessary context before Epic decomposition.
**Step 1: Load Configuration**
Auto-discovers Team ID and Next Epic Number from `docs/tasks/kanban_board.md`:
- **Team ID:** Reads Linear Configuration table → Fallback: Ask user directly
- **Next Epic Number:** Reads Next Epic Number field → Fallback: Ask user directly
**Details:** See CLAUDE.md sections "Configuration Auto-Discovery" and "Linear Integration".
**Step 2: Project Research**
**Objective:** Research project documentation AND frontend code to understand context BEFORE asking user questions.
**Process:**
1. **Document Scan:**
- Use `Glob` to find: `docs/requirements.md`, `docs/architecture.md`, `docs/tech_stack.md`
- Use `Read` to load found documents
2. **Frontend Code Scan (if applicable):**
- Use `Glob` to find: `**/*.html`, `src/**/*.html`, `public/**/*.html`, `templates/**/*.html`
- Use `Read` to load HTML files
- Extract functional domains from:
- **Navigation menus:** `<nav>`, `<a href>` links reveal feature areas
- **Forms:** Input fields reveal data models (user registration, login, checkout)
- **Page titles:** `<h1>`, `<title>` tags reveal feature names
- **Route patterns:** URL structures reveal domain boundaries
**Example HTML extraction:**
```html
<nav>
<a href="/products">Products</a>
<a href="/cart">Shopping Cart</a>
<a href="/checkout">Checkout</a>
</nav>
<!-- Reveals domains: Product Catalog, Shopping Cart, Payment -->
```
3. **Extract key information from docs + HTML:**
- **Business objectives:** What is the project trying to achieve? (from requirements.md)
- **User personas:** Who will use the system? (from requirements.md)
- **Major functional domains:** What are the main modules/areas? (from requirements.md, architecture.md, HTML navigation)
- **Technical stack:** What technologies mentioned? (from tech_stack.md, architecture.md, HTML meta/script tags)
- **Infrastructure requirements:** Any mention of logging, monitoring, deployment, CI/CD, security, performance optimization?
4. **Combine findings:**
- Merge domains from docs + HTML (deduplicate, consolidate similar)
- Example: "User Auth" (from docs) + "Login" (from HTML) → "User Management"
**Fallback:** If docs AND HTML missing → Skip to Phase 2, will ask user basic questions
**Step 3: Infrastructure Epic Decision**
**Objective:** Determine if Infrastructure Epic (Epic 0) should be proposed.
**Criteria for Infrastructure Epic:**
✅ **PROPOSE Infrastructure Epic (Epic 0)** if ANY of:
1. **New project** (no `docs/infrastructure.md` found, no Epic "Infrastructure" in kanban_board.md Epic Story Counters)
2. **Multi-stack** (requirements.md or tech_stack.md mentions frontend AND backend on different stacks - e.g., React + Python)
3. **Infrastructure requirements mentioned** in requirements.md, architecture.md:
- Logging, Error Handling
- Monitoring, Alerting
- Hosting, Deployment, CI/CD
- Security (authentication, authorization, encryption, secrets management)
- Performance optimization (caching, rate limiting, database optimization)
❌ **DO NOT propose** if:
1. Existing project (found `docs/infrastructure.md`)
2. Epic Story Counters shows existing Epic with "Infrastructure" in title
3. User explicitly declined in previous interaction
**Decision:** Store YES/NO decision for use in Phase 2
**Output from Phase 1:**
- Team ID, Next Epic Number
- Project context (business goals, domains from docs + HTML, tech stack, infrastructure needs) - if found
- Infrastructure Epic decision (YES/NO)
---
### Phase 2: Scope Analysis & Epic Planning
**Objective:** Identify logical domains and build Epic structure inline.
**Process:**
**Step 1: Auto-identify Domains**
Use research context from Phase 1 Step 2:
- If project docs found → Extract domains from requirements.md, architecture.md (module names, feature areas)
- If HTML found → Extract domains from navigation, forms, page structures
- Combine and deduplicate domains
- Example: "User Auth" + "Profile Management" → "User Management"
**Fallback:** If no docs/HTML → Ask user basic questions (scope, objectives, functional areas)
**Step 2: Build Epic List (inline)**
**IF Infrastructure needed (from Phase 1 Step 3):**
- **Epic 0: Infrastructure & Operations**
- Goal: Establish foundational infrastructure, deployment pipeline, operational capabilities
- Scope: Logging, error handling, monitoring, CI/CD, security baseline, performance
- **Multi-stack projects:** Each Story doubles (Frontend Story + Backend Story for same functionality)
- **Epic 1-N:** Business domains (from Step 1)
**ELSE:**
- **Epic 1-N:** Business domains only
**Step 3: Determine Epic Count**
- Infrastructure Epic (if applicable): +1 Epic
- Simple Initiative (1-3 domains): 3-4 Epics total
- Medium Initiative (4-6 domains): 5-7 Epics total
- Complex Initiative (7+ domains): 7-10 Epics total (rare)
- **Max 10 Epics per Initiative** (enforced)
**Step 4: Show Proposed Epic Structure (USER CONTROL POINT 1)**
Display identified Epics with initiative-internal indexes:
```
📋 Proposed Epic Structure:
Epic 0: Infrastructure & Operations
Epic 1: User Management
Epic 2: Product Catalog
Epic 3: Shopping Cart
Epic 4: Payment Processing
Epic 5: Order Management
Total: 6 Epics
Type "confirm" to proceed, or modify the list
```
**Step 5: User Confirmation**
- User types "confirm" → Proceed to Phase 3
- User modifies → Update domain list, show again
**Output:** Approved Epic list (Epic 0-N or Epic 1-N) ready for next phase
---
### Phase 3: Check Existing Epics
**Objective:** Determine CREATE vs REPLAN mode.
Query kanban_board.md and Linear for existing Epics:
1. **Read Epic Story Counters** table in kanban_board.md
2. **Count existing Epic rows** (excludes header row)
**Decision Point:**
- **Count = 0** → No existing Epics → **Proceed to Phase 4+5a (CREATE MODE)**
- **Count ≥ 1** → Existing Epics found → **Proceed to Phase 5b (REPLAN MODE)**
---
### Phase 4: Epic Preparation (CREATE mode only)
**Trigger:** Phase 3 determined Count = 0 (CREATE MODE)
**Objective:** Prepare all Epic documents before batch preview.
**Step 1: Auto-extract Information for ALL Domains**
For EACH domain (from Phase 2), extract answers to 5 key questions from project documentation:
1. **Q1: Business goal** - Why this Epic/domain matters
- **Source:** requirements.md (domain objectives section)
- **Extraction:** "The [domain] module aims to..." or "Goal: [objective]"
- **Fallback:** architecture.md (module purpose)
2. **Q2: Key features in scope** - 3-5 bullet points of capabilities
- **Source:** requirements.md (functional requirements for this domain)
- **Extraction:** Bulleted lists under domain heading, feature descriptions
- **Fallback:** architecture.md (component responsibilities)
3. **Q3: Out of scope** - Prevent scope creep
- **Source:** requirements.md (explicitly excluded features section)
- **Extraction:** "Not in scope:", "Future versions:", "Out of scope for [domain]:"
- **Fallback:** Infer from requirements.md (features NOT mentioned in domain)
4. **Q4: Success criteria** - Measurable outcomes
- **Source:** requirements.md (acceptance criteria, metrics, KPIs for domain)
- **Extraction:** Performance targets, user metrics, quality gates
- **Fallback:** Generic criteria based on domain type (e.g., "<200ms API response" for backend)
5. **Q5: Known risks** (Optional) - Blockers, dependencies
- **Source:** architecture.md (technical constraints, dependencies section)
- **Extraction:** "Risks:", "Dependencies:", "Constraints:"
- **Fallback:** User input if critical, otherwise leave as "To be determined during Story planning"
**If extraction incomplete:**
- Show extracted information to user
- Ask ONCE for ALL missing information across ALL domains (batch question, not per-domain)
- Example: "For Epic 1 (User Management), I couldn't find success criteria. For Epic 2 (Payment), I couldn't find risks. Please provide..."
**Step 2: Generate ALL Epic Documents**
For EACH domain, generate complete Epic document using epic_template_universal.md:
**Epic indexing:**
- IF Infrastructure Epic exists (from Phase 1 Step 3) → Epic 0 (Infrastructure), Epic 1-N (business domains)
- ELSE → Epic 1-N (business domains only)
**Linear Title (will be created in Phase 5a):**
- Use Next Epic Number from kanban_board.md for sequential numbering
- Format: "Epic {Next Epic Number}: {Domain Title}"
- Example: Next = 11 → "Epic 11: Infrastructure & Operations"
**Sections:** Goal, Scope In/Out, Success Criteria, Dependencies, Risks & Mitigations, Architecture Impact, Phases
**Use extracted information** from Step 1 for all sections
**Output:** All Epic documents ready (Epic 0-N), indexed within initiative
---
### Phase 5a: Epic Creation (CREATE mode)
**Trigger:** Phase 4 completed preparation
**Objective:** Show preview, get confirmation, create all Epics in Linear.
**Step 1: Show Batch Preview (USER CONTROL POINT 2)**
Display ALL generated Epics with initiative-internal indexes:
```
📋 Epic Batch Preview (6 Epics to create)
═══════════════════════════════════════════════
Epic 0: Infrastructure & Operations
═══════════════════════════════════════════════
Goal: Establish foundational infrastructure, deployment pipeline, and operational capabilities to support all business Epics
Scope In:
- Logging and error handling framework
- Monitoring and alerting system
- CI/CD pipeline (GitHub Actions)
- Security baseline (secrets management, encryption)
- Performance optimization (caching, rate limiting)
Scope Out:
- Application-specific business logic
- User-facing features
- Domain-specific integrations
Success Criteria:
- All deployments automated via CI/CD (<10 min deployment time)
- System uptime ≥99.9%
- API response time <200ms (p95)
- Security audit passed
═══════════════════════════════════════════════
Epic 1: User Management
═══════════════════════════════════════════════
Goal: Enable users to register, authenticate, and manage their accounts securely
Scope In:
- User registration with email verification
- Login/logout with JWT authentication
- Password reset flow
- Profile management
Scope Out:
- Social login (OAuth) - planned for Epic 5
- Multi-factor authentication - future version
- User roles and permissions - part of Epic 3
Success Criteria:
- User registration <2 seconds
- Login success rate >98%
- Password reset completion rate >90%
[... all other Epics ...]
───────────────────────────────────────────────
Total: 6 Epics (Epic 0: Infrastructure, Epic 1-5: Business domains)
Type "confirm" to create all Epics in Linear
```
**Step 2: User Confirmation**
- User types "confirm" → Proceed to Step 3
- User provides feedback → Adjust documents in Phase 4, regenerate preview, repeat
**Step 3: Create All Epics in Linear**
For EACH Epic (in sequential order for numbering consistency):
1. **Get Next Epic Number:**
- Read current Next Epic Number from kanban_board.md
- Example: 11
2. **Create Linear Project:**
- Title: "Epic {Next Epic Number}: {Domain Title}"
- Example: "Epic 11: Infrastructure & Operations" (for Epic 0)
- Example: "Epic 12: User Management" (for Epic 1)
- Description: Complete Epic markdown (from Phase 4 Step 2)
- Team: Team ID from Phase 1
- State: "planned"
3. **Update kanban_board.md:**
- Increment Next Epic Number by 1 in Linear Configuration table
- Add new row to Epic Story Counters: `Epic {N} | - | US001 | - | EPN_01`
- Add to "Epics Overview" → Active: `- [Epic {N}: Title](link) - Backlog`
4. **Collect URL**
**Step 4: Display Summary**
```
✅ Created 6 Epics for initiative
Epics created:
- Epic 11: Infrastructure & Operations (Epic 0 index) [link]
- Epic 12: User Management (Epic 1 index) [link]
- Epic 13: Product Catalog (Epic 2 index) [link]
- Epic 14: Shopping Cart (Epic 3 index) [link]
- Epic 15: Payment Processing (Epic 4 index) [link]
- Epic 16: Order Management (Epic 5 index) [link]
Next Epic Number updated to: 17
Next Steps:
1. Use ln-220-story-coordinator to create Stories for each Epic (run 6 times)
2. OR use ln-200-scope-decomposer to automate Epic + Story creation
```
**Output:** Created Epic URLs + summary
---
### Phase 5b: Replan Mode (Existing Epics Found)
**Trigger:** Phase 3 determined Count ≥ 1 (REPLAN MODE)
**Process:**
1. **Load Existing Epics:**
- Read Epic Story Counters table from kanban_board.md
- For each Epic row: load Epic from Linear via `get_project(id)`
- Load FULL description (Goal, Scope In/Out, Success Criteria, Risks, Phases)
- Note Epic status (active/archived)
- **Total:** N existing Epics
2. **Compare IDEAL Plan (from Phase 2) vs Existing:**
- **Match by goal:** Fuzzy match Epic goals + domain names
- **Identify operations needed:**
- **KEEP:** Epic in IDEAL + existing, goals unchanged → No action
- **UPDATE:** Epic in IDEAL + existing, scope/criteria changed → Update description
- **OBSOLETE:** Epic in existing, NOT in IDEAL → Archive (state="archived")
- **CREATE:** Epic in IDEAL, NOT in existing → Create new
3. **Categorize Operations:**
```
✅ KEEP (N Epics): No changes needed
- Epic 5: User Management
- Epic 6: Payment Processing
🔧 UPDATE (M Epics): Scope or criteria changed
- Epic 7: Reporting (Scope modified: add real-time dashboards)
- Epic 8: Notifications (Success Criteria: add email delivery tracking)
❌ OBSOLETE (K Epics): No longer in initiative scope
- Epic 9: Legacy Data Migration (removed from scope)
➕ CREATE (L Epics): New domains added
- Epic 17: Analytics Engine (new initiative requirement)
```
4. **Show Replan Summary:**
- Display operations for all Epics
- Show diffs for UPDATE operations (before/after Scope, Criteria)
- Show warnings for edge cases:
- ⚠️ "Epic 7 has 5 Stories In Progress - cannot auto-archive, manual review needed"
- Total operation count
5. **User Confirmation:**
- Wait for user to type "confirm"
- If user provides feedback → Adjust operations and show updated summary
6. **Execute Operations:**
- **KEEP:** Skip (no Linear API calls)
- **UPDATE:** Call `update_project(id, description=new_description)` (if no Stories In Progress)
- **OBSOLETE:** Call `update_project(id, state="archived")` (if no Stories In Progress)
- **CREATE:** Call `create_project()` (same as Phase 5a Step 3) + update kanban_board.md
7. **Update kanban_board.md:**
- Remove OBSOLETE Epics from Epic Story Counters table
- Update modified Epics (UPDATE operations) - preserve Story counters
- Add new Epics (CREATE operations) to Epic Story Counters
- Update Epics Overview section (move archived to Archived section)
**Output:** Summary message with operation results + affected Epic URLs
**Important Constraints:**
- **Never auto-update/archive Epics with Stories In Progress** (show warnings only)
- **Never delete Epics:** Use state="archived" to preserve history
- **Always require user confirmation** before executing operations
---
## Definition of Done
Before completing work, verify ALL checkpoints:
**✅ Discovery Complete (Phase 1):**
- [ ] Team ID loaded from kanban_board.md
- [ ] Next Epic Number loaded from kanban_board.md
- [ ] Documentation scanned (requirements.md, architecture.md, tech_stack.md)
- [ ] HTML files scanned (if frontend exists)
- [ ] Infrastructure Epic decision made (YES/NO based on project conditions)
**✅ Scope Analysis Complete (Phase 2):**
- [ ] Domains auto-identified from docs + HTML
- [ ] Infrastructure Epic (Epic 0) included if applicable
- [ ] Epic list built (Epic 0-N or Epic 1-N)
- [ ] User confirmed Epic structure (CONTROL POINT 1)
**✅ Existing Epics Checked (Phase 3):**
- [ ] Epic Story Counters read from kanban_board.md
- [ ] Existing Epic count determined (0 → CREATE, ≥1 → REPLAN)
**✅ Epic Preparation Complete (Phase 4 - CREATE only):**
- [ ] Q1-Q5 auto-extracted for ALL domains
- [ ] User provided missing information if needed (batch question)
- [ ] ALL Epic documents generated (Epic 0-N indexes)
**✅ Epic Creation Complete (Phase 5a - CREATE only):**
- [ ] Batch preview shown with Epic 0-N indexes
- [ ] User confirmed preview (CONTROL POINT 2)
- [ ] ALL Epics created in Linear with "Epic {N}: {Title}" format (N = Next Epic Number)
- [ ] kanban_board.md updated after EACH Epic:
- Next Epic Number incremented by 1
- Epic Story Counters row added
- Epics Overview updated
- [ ] Summary displayed with all Epic URLs
**✅ Epic Replan Complete (Phase 5b - REPLAN only):**
- [ ] Existing Epics loaded from Linear
- [ ] IDEAL plan compared against existing
- [ ] Operations categorized (KEEP/UPDATE/OBSOLETE/CREATE)
- [ ] User confirmed operations (CONTROL POINT 2)
- [ ] Operations executed in Linear
- [ ] kanban_board.md updated (removed OBSOLETE, added CREATE)
- [ ] Summary displayed with affected Epic URLs
**Output:** List of Linear Project URLs (Epic {N}: {Title}) + Next Epic Number value
---
## Example Usage
**Request:**
```
"Create epics for e-commerce platform"
```
**Process:**
1. **Phase 1: Discovery & Research**
- Team "Product", Next Epic Number = 11
- Scan requirements.md, architecture.md, tech_stack.md
- Scan HTML files: Found navigation with Products, Cart, Checkout
- Infrastructure Epic decision: YES (new project, multi-stack: React + Python)
2. **Phase 2: Scope Analysis**
- Auto-identify 6 domains from docs + HTML: "Infrastructure", "User Management", "Product Catalog", "Shopping Cart", "Payment Processing", "Order Management"
- Build Epic list: Epic 0 (Infrastructure) + Epic 1-5 (business)
- Show proposed Epic structure → User confirms
3. **Phase 3: Check Existing**
- Epic Story Counters: 0 rows → CREATE MODE
4. **Phase 4: Epic Preparation**
- Auto-extract Q1-Q5 for all 6 domains from requirements.md, architecture.md, HTML
- Generate 6 Epic documents (Epic 0-5 indexes)
5. **Phase 5a: Epic Creation**
- Show batch preview with Epic 0-5 indexes
- User types "confirm"
- Create in Linear sequentially:
- Epic 0 → Linear: "Epic 11: Infrastructure & Operations"
- Epic 1 → Linear: "Epic 12: User Management"
- Epic 2 → Linear: "Epic 13: Product Catalog"
- Epic 3 → Linear: "Epic 14: Shopping Cart"
- Epic 4 → Linear: "Epic 15: Payment Processing"
- Epic 5 → Linear: "Epic 16: Order Management"
- Next Epic Number updated to 17
- Display summary with all 6 URLs
**Result:** 6 Epics created (Epic 0-5 internal indexes, Epic 11-16 Linear titles)
---
## Reference Files
- **linear_integration.md:** Discovery patterns + Linear API reference
- **epic_template_universal.md:** Epic template structure
---
## Best Practices
- **Research project docs first:** Always scan requirements.md, architecture.md, tech_stack.md in Phase 1 Step 2 BEFORE asking user
- **Scan HTML files:** Extract functional domains from navigation, forms, page titles (Phase 1 Step 2) - complements documentation
- **Propose Infrastructure Epic:** For new projects, multi-stack, or projects with security/monitoring/deployment requirements (Phase 1 Step 3)
- **Epic 0 for Infrastructure:** Use Epic 0 as reserved index for Infrastructure Epic within initiative, business domains start from Epic 1 (Phase 2 Step 2)
- **Business Epic grouping:** Group domains by complete business process OR HTML screen
- ✅ BY BUSINESS PROCESS: "User Authentication" (login + register + password reset + profile)
- ✅ BY HTML SCREEN: "Product Catalog" (products list page + product details page + search)
- ❌ AVOID: "Login Screen", "Register Screen" as separate Epics (too granular, merge into "User Authentication")
- ❌ AVOID: "User Table", "Login Service" (technical components, not business domains)
- **Guideline:** 1 Epic = 5-10 User Stories = 1 complete business capability or major UI screen group
- **Batch Epic preview:** Generate ALL Epics before showing preview - allows user to see complete Epic plan with Epic 0-N indexes (Phase 5a Step 1)
- **Auto-extraction:** Extract Q1-Q5 from requirements.md, architecture.md, HTML BEFORE asking user (Phase 4 Step 1) - ask only for missing information
- **Linear Title format:** "Epic {Next Epic Number}: {Domain}" where Next Epic Number from kanban_board.md (Phase 5a Step 3)
- **Business-focused Scope:** Epic Scope In lists USER CAPABILITIES, not technical tasks
- ✅ GOOD: "Users can register, login, logout, reset password"
- ❌ BAD: "Create user table, JWT middleware, password hashing service"
- Technical architecture → Epic "Architecture Impact" section, NOT Scope In
- **Measurable success criteria:** "<200ms" not "fast", ">98% login rate" not "reliable"
- **Define OUT of scope:** Prevent scope creep with explicit exclusions
- **No code snippets:** Never include actual code in Epic descriptions - only high-level features and goals
---
**Version:** 7.0.0 (BREAKING: Epic 0 clarified as initiative-internal index. HTML research added to Phase 1 Step 2 for frontend domain extraction. Phase structure simplified - removed old Phase 3 "Build IDEAL Plan" (merged into Phase 2 inline). Phase 4 extracted from Phase 5a for Epic Preparation. Phase numbering updated: Phase 3=Check Existing, Phase 4=Preparation, Phase 5a/5b=Creation/Replan. Linear titles use Next Epic Number consistently. Removed confusing "conceptual numbering" explanations.)
**Last Updated:** 2025-11-20

136
skills/ln-210-epic-coordinator/diagram.html Normal file
View File

@@ -0,0 +1,136 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>ln-210-epic-coordinator - State Diagram</title>
<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
<link rel="stylesheet" href="../shared/css/diagram.css">
</head>
<body>
<div class="container">
<header>
<h1>🎯 ln-210-epic-coordinator</h1>
<p class="subtitle">Epic Coordinator - State Diagram v7.0.0</p>
</header>
<div class="info-box">
<h3>📋 Workflow Overview</h3>
<ul>
<li><strong>Purpose:</strong> Decompose scope/initiative into 3-7 Epics (Linear Projects)</li>
<li><strong>Modes:</strong> CREATE (batch preview → create ALL Epics) / REPLAN (compare IDEAL vs EXISTING → execute operations)</li>
<li><strong>Pattern:</strong> Batch Preview (show ALL Epics) → Single Confirm → Create ALL</li>
<li><strong>Output:</strong> 3-7 Linear Projects with Epic documents (Epic 0: Infrastructure, Epic 1-N: Business domains)</li>
</ul>
</div>
<div class="legend">
<div class="legend-item">
<div class="legend-color color-discovery"></div>
<span>Discovery/Research</span>
</div>
<div class="legend-item">
<div class="legend-color color-loop"></div>
<span>Preparation</span>
</div>
<div class="legend-item">
<div class="legend-color color-decision"></div>
<span>Decision Point</span>
</div>
<div class="legend-item">
<div class="legend-color color-action"></div>
<span>Creation/Completion</span>
</div>
</div>
<div class="diagram-container">
<div class="mermaid">
graph TD
Start([Start: Create/Replan Epics]) --> Phase1[Phase 1: Discovery & Research<br/>Auto-discover Team ID + Next Epic Number<br/>Scan docs + HTML files<br/>Infrastructure Epic decision]
Phase1 --> Phase2[Phase 2: Scope Analysis<br/>Auto-identify domains from docs + HTML<br/>Build Epic list Epic 0-N<br/>Show proposed structure]
Phase2 --> UserConfirm1{User confirms<br/>Epic structure?}
UserConfirm1 -->|No| Phase2
UserConfirm1 -->|Yes| Phase3[Phase 3: Check Existing Epics<br/>Count rows in Epic Story Counters]
Phase3 --> Decision{Existing<br/>Epics count?}
Decision -->|Count = 0<br/>CREATE MODE| Phase4[Phase 4: Epic Preparation<br/>Auto-extract Q1-Q5 for ALL domains<br/>Generate ALL Epic documents]
Phase4 --> Phase5a[Phase 5a: Epic Creation<br/>Show batch preview Epic 0-N]
Phase5a --> UserConfirm2{User types<br/>'confirm'?}
UserConfirm2 -->|No| Phase4
UserConfirm2 -->|Yes| CreateAll[Create ALL Epics in Linear<br/>Epic 0 → Epic 11: Infrastructure<br/>Epic 1 → Epic 12: User Management<br/>etc.]
CreateAll --> Summary1[Display summary<br/>6 Epics created Epic 11-16]
Summary1 --> End([End])
Decision -->|Count ≥ 1<br/>REPLAN MODE| Phase5b[Phase 5b: Epic Replan<br/>Load existing Epics<br/>Compare IDEAL vs EXISTING<br/>Categorize operations]
Phase5b --> Operations[Show operations:<br/>KEEP / UPDATE / OBSOLETE / CREATE]
Operations --> UserConfirm3{User confirms<br/>operations?}
UserConfirm3 -->|No| End
UserConfirm3 -->|Yes| Execute[Execute operations in Linear<br/>Update kanban_board.md]
Execute --> Summary2[Display summary<br/>Operation results + affected URLs]
Summary2 --> End
%% Styling
classDef discovery fill:#E3F2FD,stroke:#1976D2,stroke-width:2px
classDef loop fill:#FFF9C4,stroke:#F57C00,stroke-width:2px
classDef decision fill:#FFE0B2,stroke:#E64A19,stroke-width:2px
classDef action fill:#C8E6C9,stroke:#388E3C,stroke-width:2px
class Phase1,Phase2 discovery
class Phase4,Phase5a,Phase5b,Operations,Execute loop
class Decision,UserConfirm1,UserConfirm2,UserConfirm3 decision
class Phase3,CreateAll,Summary1,Summary2 action
</div>
</div>
<div class="info-box">
<h3>🔑 Key Features v7.0.0</h3>
<ul>
<li><strong>HTML Research:</strong> Extract domains from navigation, forms, page titles (complements documentation)</li>
<li><strong>Epic 0 Reserved:</strong> Infrastructure Epic = Epic 0 index, business domains = Epic 1-N</li>
<li><strong>Batch Preview:</strong> Show ALL Epics before creation, single confirmation (not sequential loop)</li>
<li><strong>Auto-extraction Q1-Q5:</strong> Goal, Scope In/Out, Success Criteria, Risks from docs + HTML</li>
<li><strong>CREATE/REPLAN Modes:</strong> Decompose-First Pattern - builds IDEAL plan, compares with existing, determines operations</li>
<li><strong>Business Epic Grouping:</strong> 1 Epic = complete business process OR HTML screen group (5-10 Stories)</li>
</ul>
</div>
<div class="info-box">
<h3>📐 Phase Structure</h3>
<ul>
<li><strong>Phase 1:</strong> Discovery & Research (Team ID, docs, HTML, Infrastructure decision)</li>
<li><strong>Phase 2:</strong> Scope Analysis (identify domains, build Epic list, user confirms structure)</li>
<li><strong>Phase 3:</strong> Check Existing Epics (determine CREATE vs REPLAN mode)</li>
<li><strong>Phase 4:</strong> Epic Preparation (CREATE only - auto-extract, generate docs)</li>
<li><strong>Phase 5a:</strong> Epic Creation (CREATE only - batch preview, confirm, create ALL)</li>
<li><strong>Phase 5b:</strong> Epic Replan (REPLAN only - compare, show operations, execute)</li>
</ul>
</div>
<footer>
<p>Generated for ln-210-epic-coordinator skill | Version 7.0.0</p>
<p>Diagram format: Mermaid.js | Last updated: 2025-11-20</p>
</footer>
</div>
<script>
mermaid.initialize({
startOnLoad: true,
theme: 'default',
flowchart: {
useMaxWidth: true,
htmlLabels: true,
curve: 'basis'
}
});
</script>
</body>
</html>

95
skills/ln-210-epic-coordinator/references/epic_template_universal.md Normal file
View File

@@ -0,0 +1,95 @@
# Epic N: Epic Title
**Linear Project:** [Epic Title](https://linear.app/workspace/project/...)
**Priority:** High | Medium | Low
---
## Goal
Brief business objective this Epic achieves. Focus on "why" and business value.
---
## Scope
### In Scope
- Feature/capability 1
- Feature/capability 2
- Feature/capability 3
### Out of Scope
- Explicitly NOT doing in this Epic
- Future enhancements deferred
- Related but not included features
---
## Success Criteria
Measurable outcomes to verify Epic completion:
- Measurable outcome 1 (quantifiable)
- Measurable outcome 2 (testable)
- Measurable outcome 3 (observable)
---
## Dependencies
### Technical Dependencies
- **Dependency 1**: Technical requirement description
- **Dependency 2**: Infrastructure/library requirement
### External Dependencies
- **Third-party services**: Which external services required?
- **Infrastructure**: What infrastructure needed?
### Epic Dependencies
- **Blocks**: This Epic blocks [Epic Name]
- **Blocked by**: This Epic is blocked by [Epic Name]
---
## Risks and Mitigations
| Risk | Impact | Probability | Mitigation Strategy |
|------|--------|-------------|---------------------|
| Risk description 1 | H/M/L | H/M/L | How to address |
| Risk description 2 | H/M/L | H/M/L | How to address |
---
## Metrics
How to measure success after deployment:
- **Metric 1**: Target: [value], Measurement: [how]
- **Metric 2**: Target: [value], Measurement: [how]
---
## Architecture Impact
### Components Affected
- Component 1 - Description of changes
- Component 2 - Description of changes
### Architecture Patterns Applied
- Pattern 1: Description and why chosen
- Pattern 2: Description and why chosen
### Technical Decisions
- Decision 1: Rationale
- Decision 2: Trade-offs considered
---
## User Stories
User Stories created separately via story-creator skill:
- US001: [Story Name] - Brief description
- US002: [Story Name] - Brief description
---
**Template Version:** 2.1.0 (Timeline removed)
**Last Updated:** 2025-11-07

372
skills/ln-210-epic-coordinator/references/linear_integration.md Normal file
View File

@@ -0,0 +1,372 @@
# Linear Integration Guide
Discovery and API reference for creating Linear Projects (Epics) and User Stories.
---
## Part 1: Discovery
Auto-discovering Linear configuration from centralized source.
### Finding Team ID
**Primary source:** `docs/tasks/kanban_board.md`
Read Linear Configuration table:
```markdown
## Linear Configuration
| Variable | Value |
|----------|-------|
| **Team ID** | PrompsitAPI |
| **Team Key** | API |
| **Next Epic Number** | 7 |
```
Extract **Team ID** value from table.
**Fallback:** Ask user "What is your Linear team ID?" (formats: "PrompsitAPI", "API")
### Finding Next Epic Number
**Primary source:** `docs/tasks/kanban_board.md`
Read Linear Configuration table → **Next Epic Number** field.
**Verification (optional):** Query Linear Projects via MCP to verify:
```
mcp__linear-server__list_projects(team="<TEAM_ID>")
```
Extract Epic numbers from project names matching `Epic \d+`, take MAX.
**Fallback:** Ask user "What is the next Epic number?" (formats: "7", "1" if first)
### Finding Next Story Number
**Primary source:** `docs/tasks/kanban_board.md`
Read Epic Story Counters table:
```markdown
### Epic Story Counters
| Epic | Last Story | Next Available |
|------|-----------|----------------|
| Epic 6 | - | US001 |
| Epic 7+ | - | US001 |
```
For specified Epic → Read **Next Available** column.
**Format:** US001, US002, US010 (zero-padded, 3 digits)
**Fallback:** Ask user "What is the next Story number for Epic N?" (default: "US001")
---
## Part 2: Create Project API
### MCP Function
```
mcp__linear-server__create_project(
name: str, # Required - "Epic N: Title"
team: str, # Required - Team ID/key
description: str = "", # Full Epic markdown
startDate: str = "", # ISO format YYYY-MM-DD
targetDate: str = "", # ISO format YYYY-MM-DD
summary: str = "" # Max 255 chars
)
```
### Parameters
**name** (required):
- Format: "Epic N: Title"
- Example: "Epic 7: OAuth2 Authentication"
**team** (required):
- Team ID or key
- Example: "API", "PrompsitAPI"
**description** (optional):
- Full Epic content in Markdown
- Includes: Goal, Scope, Success Criteria, Risks
**summary** (optional):
- One-sentence goal (max 255 chars)
- Example: "Implement OAuth2 authentication for API security"
### Return Value
```
{
"success": True,
"projectId": "abc123-xyz",
"url": "https://linear.app/workspace/project/abc123"
}
```
### Example Usage
```
result = mcp__linear-server__create_project(
name="Epic 7: OAuth2 Authentication",
team="API",
description="""
# Goal
Enable secure API authentication using OAuth2.
## In Scope
- Token generation and validation
- Refresh token flow
- User profile API
## Out of Scope
- Password reset
- Social login
## Success Criteria
- Auth endpoint responds <200ms p95
- 99.9% uptime
- Zero security vulnerabilities
""",
summary="Implement OAuth2 authentication for API security",
startDate="2025-10-24",
targetDate="2025-12-15"
)
# Returns URL to created project
```
### Error Handling
**Team not found:** Verify team exists, check spelling
**Invalid date:** Use "YYYY-MM-DD" format only
**Creation failed:** Create minimal project (name + team only), add details in Linear UI
---
## Part 3: Create Issue API (User Stories)
### MCP Function
```
mcp__linear-server__create_issue(
title: str, # Required - "USXXX: Title"
team: str, # Required - Team ID/key
description: str = "", # Full Story markdown
project: str = "", # Epic name to link to
labels: list = [], # ["user-story"] for parent stories
parentId: str = None # null for User Stories, Story ID for tasks
)
```
### Parameters for User Stories
**title** (required):
- Format: "USXXX: Title"
- Example: "US001: Token Generation Service"
**team** (required):
- Team ID or key
- Example: "API", "PrompsitAPI"
**description** (optional):
- Full Story content in Markdown
- Includes: Story (As a..), Context, AC, Technical Notes, DoD
**project** (optional):
- Epic name to link story to
- Example: "Epic 7: OAuth2 Authentication"
**labels** (required for User Stories):
- Must include: ["user-story"]
- Identifies as parent for tasks
**parentId** (required):
- Set to null for User Stories (they are parents)
- Set to Story ID for tasks (children)
### Return Value
```
{
"success": True,
"issueId": "API-123",
"url": "https://linear.app/workspace/issue/API-123"
}
```
### Example Usage
```
result = mcp__linear-server__create_issue(
title="US001: OAuth Token Authentication",
team="API",
description="""
## Story
**As a** mobile app developer
**I want** to authenticate API requests with OAuth2 tokens
**So that** users can securely access their data
## Acceptance Criteria
- **Given** valid token **When** request sent **Then** returns 200
- **Given** invalid token **When** request sent **Then** returns 401
""",
project="Epic 7: OAuth2 Authentication",
labels=["user-story"],
parentId=None
)
# Returns URL to created User Story
```
### Error Handling
**Team not found:** Verify team exists, check spelling
**Project not found:** Verify Epic name matches exactly in Linear
**Creation failed:** Create minimal issue (title + team only), add details in Linear UI
---
## Part 4: Get Issue and List Issues APIs
### Why Needed?
- `create_issue` returns only **short ID** (e.g., "API-123")
- `list_issues(parentId=...)` requires **UUID** (e.g., "333e6aa2-64d6-47de-b07b-7385756ae014")
- Must use `get_issue` to retrieve UUID from short ID
### Get Issue API
**MCP Function:**
```
mcp__linear-server__get_issue(
id: str # Short ID (API-123) OR UUID
)
```
**Parameters:**
**id** (required):
- Accepts: Short ID (e.g., "API-123", "US001") OR UUID
- Example: "API-97" or "333e6aa2-64d6-47de-b07b-7385756ae014"
**Return Value:**
Full issue object with:
- **id**: UUID (internal Linear ID) - "333e6aa2-64d6-47de-b07b-7385756ae014"
- **identifier**: Short ID - "API-123"
- **title**: Issue title
- **description**: Full markdown description
- **state**: Current status
- **labels**: Array of labels
- **parentId**: Parent issue UUID (for child tasks)
- **project**: Epic/Project object
- Other fields: assignee, createdAt, updatedAt, etc.
**Example Usage:**
```python
# Get Story by short ID
story = mcp__linear-server__get_issue(id="API-97")
story_uuid = story["id"] # Extract UUID: "333e6aa2-64d6-47de-b07b-7385756ae014"
story_short_id = story["identifier"] # "API-97"
```
### List Issues API
**MCP Function:**
```
mcp__linear-server__list_issues(
team: str = None, # Team name/ID
parentId: str = None, # ⚠️ MUST BE UUID, NOT short ID
state: str = None, # Filter by state
labels: list = None, # Filter by labels
limit: int = 50 # Max results
)
```
**Critical Parameter:**
**parentId** (optional):
- ⚠️ **MUST BE UUID**, NOT short ID
- ❌ Wrong: `parentId="API-97"` (short ID) - **WILL FAIL**
- ✅ Correct: `parentId="333e6aa2-64d6-47de-b07b-7385756ae014"` (UUID)
**Example Usage:**
```python
# WRONG - will fail with error
tasks = mcp__linear-server__list_issues(
parentId="API-97" # ❌ Short ID doesn't work
)
# CORRECT - get UUID first
story = mcp__linear-server__get_issue(id="API-97")
story_uuid = story["id"] # Extract UUID
tasks = mcp__linear-server__list_issues(
parentId=story_uuid # ✅ Use UUID
)
```
### Workflow Pattern
**When fetching child tasks:**
```python
# Step 1: Get parent Story by short ID (from user input)
story_short_id = "API-97" # From user or kanban_board.md
story = mcp__linear-server__get_issue(id=story_short_id)
# Step 2: Extract UUID from Story object
story_uuid = story["id"] # "333e6aa2-64d6-47de-b07b-7385756ae014"
# Step 3: Fetch child Tasks using UUID as parentId
child_tasks = mcp__linear-server__list_issues(
parentId=story_uuid, # ✅ Must use UUID
limit=50
)
# Result: List of all child Tasks for this Story
```
**When creating child task:**
```python
# Step 1: Get parent Story UUID (same as above)
story = mcp__linear-server__get_issue(id="API-97")
story_uuid = story["id"]
# Step 2: Create child task with UUID as parentId
result = mcp__linear-server__create_issue(
title="Task: Implement feature",
team="API",
description="Task description...",
parentId=story_uuid, # ✅ Must use UUID
labels=[]
)
```
### Error Handling
**Issue not found:**
- Verify short ID exists in Linear
- Check team context (issue might be in different team)
**Empty list returned:**
- Verify parentId is UUID, not short ID
- Check if Story has any child tasks (may be legitimately empty)
- Verify Story status (canceled stories may not show tasks)
---
**Version:** 4.0.0 (Added Part 4: Get Issue and List Issues)
**Last Updated:** 2025-11-03
**Changes from v3.0.0:**
- Added Part 4 with get_issue and list_issues documentation
- Explained UUID vs short ID distinction
- Provided workflow patterns for fetching child tasks and creating child issues

456
skills/ln-220-story-coordinator/SKILL.md Normal file
View File

@@ -0,0 +1,456 @@
---
name: ln-220-story-coordinator
description: CREATE/REPLAN Stories for Epic (5-10 Stories). Delegates ln-221-standards-researcher for standards research. Decompose-First Pattern. Auto-discovers team/Epic.
---
# Story Coordinator
Universal Story management coordinator that delegates CREATE/REPLAN operations to specialized workers after building IDEAL Story plan.
## When to Use This Skill
Use when:
- Decompose Epic to User Stories (5-10 Stories covering Epic scope)
- Update existing Stories when Epic requirements change
- Rebalance Story scopes within Epic
- Add new Stories to existing Epic structure
## Core Pattern: Decompose-First
**Key principle:** Build IDEAL Story plan FIRST, THEN check existing Stories to determine mode:
- **No existing Stories** → CREATE MODE (delegate to ln-222-story-creator)
- **Has existing Stories** → REPLAN MODE (delegate to ln-223-story-replanner)
**Rationale:** Ensures consistent Story decomposition based on current Epic requirements, independent of existing Story structure (may be outdated).
## Story Numbering Convention
**Rule:** Stories start from Story 1 (US001), NO Story 0 reserved.
**Rationale:**
- Epic 0 = Infrastructure **Epic** (group of 5-10 Stories like any other Epic)
- Stories within Epic 0 numbered normally: US001, US002, ... US010
- No reserved Story 0 (unlike Epics, Stories don't need infrastructure placeholder)
**Numbering within Epic:**
- Epic 0: Infrastructure → US001-US010 (logging, monitoring, CI/CD Stories)
- Epic 1: User Management → US011-US020 (registration, login, profile Stories)
- Epic 2: Product Catalog → US021-US030 (product list, search, details Stories)
**Next Story Number:** Incremented sequentially across ALL Epics (read from kanban_board.md Epic Story Counters table)
## How It Works
### Phase 1: Context Assembly
**Objective:** Gather context for Story planning (Epic details, planning questions, frontend context, fallback docs, user input)
**Step 1: Discovery (Automated)**
Auto-discovers from `docs/tasks/kanban_board.md`:
1. **Team ID:** Reads Linear Configuration table
2. **Epic:** Parses Epic number from request → Validates in Linear → Loads Epic description
- **User format:** "Epic N" (Linear Project number, e.g., "Epic 7: OAuth Authentication")
- **Query:** `get_project(query="Epic N")` → Fetch full Epic document
- **Extract:** Goal, Scope In/Out, Success Criteria, Technical Notes (Standards Research if Epic created by ln-210 v7.0.0+)
- **Note:** Epic N = Linear Project number (global), NOT initiative-internal index (Epic 0-N)
3. **Next Story Number:** Reads Epic Story Counters table → Gets next sequential number
**Step 2: Extract Planning Information (Automated)**
Parses Epic structure for Story planning questions:
| Question | Extraction Source |
|----------|-------------------|
| **Q1 - User/Persona** | Epic Goal ("Enable [persona]...") + Scope In (user roles) |
| **Q2 - What they want** | Epic Scope In (capabilities) + functional requirements |
| **Q3 - Why it matters** | Epic Success Criteria (metrics) + Goal (business value) |
| **Q4 - Which Epic** | Already from Step 1 |
| **Q5 - Main AC** | Derive from Epic Scope In features → testable scenarios |
| **Q6 - Application type** | Epic Technical Notes (UI/API mentioned) → Default: API |
**Step 3: Frontend Research (Optional)**
**Trigger:** If Q2 (capabilities) OR Q5 (AC) missing after Step 2
**Process:**
1. Scan HTML files: `Glob` `**/*.html`, `src/**/*.html`
2. Extract:
- Forms → AC scenarios (e.g., `<form id="login">` → "Given valid credentials, When submit, Then login success")
- Buttons/Actions → capabilities (e.g., `<button id="register">` → "User registration")
- Validation rules → edge case AC (e.g., `minlength="8"` → "Given password <8 chars, Then error")
3. Combine with Epic context, deduplicate, prioritize Epic AC if conflict
**Fallback:** If no HTML → Skip to Step 4
**Step 4: Fallback Search Chain**
**Objective:** Fill missing Q1-Q6 BEFORE asking user.
For each question with no answer from Step 2-3:
| Question | Fallback Search |
|----------|-----------------|
| **Q1 (User/Persona)** | Search `requirements.md` for "User personas", "Actors" → Default "User" if not found |
| **Q3 (Why it matters)** | Search `requirements.md` for "Business objectives", "Goals" → Infer from Epic Success Criteria |
| **Q6 (Application type)** | Search `tech_stack.md` for "Frontend", "Backend", "API" → Default "API" |
**Skip:** Q2, Q5 (Epic + HTML are sources of truth), Q4 (already known)
**Step 5: User Input (Only if Missing)**
**If still missing after Step 2 + 3 + 4:**
- Show extracted: "From Epic: [Epic info]. From HTML: [HTML info]. From fallback: [fallback info]"
- Ask user to confirm or provide remaining missing details
**If all questions answered from Epic OR HTML OR fallback:** Skip user prompts, proceed to Phase 2
**Output:** Complete context (Epic details, next Story number, Q1-Q6 answers)
---
### Phase 2: Standards Research (Delegated)
**Objective:** Research industry standards/patterns BEFORE Story generation to ensure implementation follows best practices.
**Why:** Prevents outdated patterns or RFC violations (e.g., OAuth without PKCE).
**Process:**
1. **Parse Epic for domain keywords:** Extract domain from Epic goal/Scope In (authentication, rate limiting, payments)
2. **Delegate to ln-221-standards-researcher:**
- Call `Skill(skill: "ln-221-standards-researcher", epic_description="[Epic full description]", story_domain="[domain]")`
- Wait for Standards Research (Markdown string)
3. **Store:** Cache for Phase 5a/5b (workers insert in Story Technical Notes)
**Output:** Standards Research stored for ALL Stories in Epic
**Skip conditions:**
- Epic has NO standards in Technical Notes
- Story domain is trivial CRUD
- Epic says "research not needed"
**Time-box:** 15-20 minutes (handled by ln-221)
**Note:** Research done ONCE per Epic, results reused for all Stories (5-10 Stories benefit from single research)
---
### Phase 3: Planning
**Objective:** Build IDEAL Story plan, determine execution mode
**Story Grouping Guidelines:**
Each Story = ONE vertical slice of user capability (end-to-end: UI → API → Service → DB).
**✅ GOOD Story Grouping (1 Story = 1 user journey):**
- ✅ "User registration" (form → validation → API → database → email)
- ✅ "Password reset" (request link → verify token → set password → update DB)
- ✅ "Product search" (input → filter/sort → API → DB query → display)
**❌ BAD Story Grouping (horizontal slices):**
- ❌ "Create user table" (database only, no user value → Task, not Story)
- ❌ "User registration API endpoint" (API layer only, not vertical)
- ❌ "Registration UI form" (frontend only, not vertical)
**Rule:** 1 Story = 1 user capability = 3-5 AC = 6-20 hours = 10-28 tests
**Build IDEAL Plan (Automated):**
1. **Analyze Epic Scope:** Review features in Epic Scope In, identify user capabilities
2. **Determine Story Count:**
- Simple Epic (1-3 features): 3-5 Stories
- Medium Epic (4-7 features): 6-8 Stories
- Complex Epic (8+ features): 8-10 Stories
- **Max 10 Stories per Epic**
3. **Story Size Guidelines:**
| Criterion | Min | Max | Under-decomposed | Over-decomposed |
|-----------|-----|-----|------------------|-----------------|
| **AC** | 3 | 5 | >5 AC (split) | <3 AC (merge) |
| **Duration** | 6h | 20h | >20h (split) | <6h (merge) |
| **Tests** | 10 | 28 | >28 tests (split) | <10 tests (merge) |
**Over-decomposition indicators:**
- ❌ <3 AC, <6 hours, <10 tests
- ❌ Purely technical (no user value)
- ❌ Title starts with "Add", "Create", "Update" (likely Task)
- ❌ Crosses only 1-2 layers (not vertical)
4. **Build IDEAL Plan "in mind":**
- Each Story: persona + capability + business value
- Each Story: 3-5 testable AC (Given-When-Then)
- Stories ordered by dependency
- Each Story: Test Strategy (Risk-Based: 2-5 E2E, 3-8 Integration, 5-15 Unit, 10-28 total)
- Each Story: Technical Notes (architecture, integrations, **Standards Research from Phase 2**, guide links)
**INVEST Checklist:**
| Criterion | Check | ✅ GOOD | ❌ BAD |
|-----------|-------|---------|--------|
| **Independent** | Can develop/deploy without blocking others | "Request OAuth token" (independent) | "Validate token" depends on "Request token" (merge or ensure API contract) |
| **Negotiable** | AC focus on WHAT, not HOW | "User gets valid token" (what) | "Use authlib 1.3.0, store in Redis" (how) |
| **Valuable** | Clear business value | "User refreshes expired token to maintain session" | "Add token_refresh table" (no user value) |
| **Estimable** | Can estimate 6-20h | Clear scope, known patterns, researched standards | "Implement authentication" (too vague) |
| **Small** | Fits 1-2 sprints | 3-5 AC, 6-20h, 10-28 tests | "Full OAuth flow" (>5 AC, >20h) |
| **Testable** | AC measurable | "Given valid refresh token, Then receive token <200ms" | "Token refresh should be fast" (not measurable) |
**Output:** IDEAL Story plan (5-10 Stories) with titles, statements, core AC, ordering
---
### Phase 4: Check Existing & Detect Mode
**Objective:** Determine execution mode based on existing Stories AND user intent
**Process:**
Query Linear for existing Stories in Epic:
```
list_issues(project=Epic.id, label="user-story")
```
**Mode Detection:**
1. **Analyze user request** for keywords:
- ADD keywords: "add story", "one more story", "additional story", "append"
- REPLAN keywords: "update plan", "revise", "requirements changed", "replan stories"
2. **Decision matrix:**
| Condition | Mode | Delegate To |
|-----------|------|-------------|
| Count = 0 | **CREATE** | Phase 5a: ln-222-story-creator |
| Count ≥ 1 AND ADD keywords | **ADD** | Phase 5c: ln-222-story-creator (appendMode) |
| Count ≥ 1 AND REPLAN keywords | **REPLAN** | Phase 5b: ln-223-story-replanner |
| Count ≥ 1 AND ambiguous | **ASK USER** | "Add new Story or revise the plan?" |
**Important:** Orchestrator loads metadata ONLY (ID, title, status). Workers load FULL descriptions (token efficiency).
**Output:** Execution mode determined + existingCount for workers
---
### Phase 5a: Delegate CREATE (No Existing Stories)
**Trigger:** Epic has no Stories yet (first decomposition)
**Delegation:**
Call ln-222-story-creator via Skill tool:
```javascript
Skill(
skill: "ln-222-story-creator",
epicData: {id, title, description},
idealPlan: [ /* 5-10 Stories from Phase 3 */ ],
standardsResearch: "Standards Research from Phase 2",
teamId: "team-id",
autoApprove: false // or true for automation
)
```
**Worker handles:**
- Generate Story documents (8 sections, insert Standards Research)
- Validate INVEST criteria
- Show preview
- User confirmation (if autoApprove=false)
- Create in Linear (project=Epic, labels=user-story, state=Backlog)
- Update kanban_board.md (Epic Grouping Algorithm)
**Output:** Created Story URLs + summary from worker
---
### Phase 5b: Delegate REPLAN (Existing Stories Found)
**Trigger:** Epic already has Stories (requirements changed)
**Delegation:**
Call ln-223-story-replanner via Skill tool:
```javascript
Skill(
skill: "ln-223-story-replanner",
epicData: {id, title, description},
idealPlan: [ /* 5-10 Stories from Phase 3 */ ],
standardsResearch: "Standards Research from Phase 2",
existingCount: N,
teamId: "team-id",
autoApprove: false // or true for automation
)
```
**Worker handles:**
- Load existing Stories (Progressive Loading: ONE BY ONE for token efficiency)
- Compare IDEAL vs existing (KEEP/UPDATE/OBSOLETE/CREATE operations)
- Show replan summary with diffs (AC, Standards Research, Technical Notes)
- User confirmation (if autoApprove=false)
- Execute operations (respecting status constraints: Backlog/Todo only, warnings for In Progress/Review/Done)
- Update kanban_board.md (add NEW Stories only via Epic Grouping Algorithm)
**Output:** Operation results + warnings + affected Story URLs from worker
---
### Phase 5c: Delegate ADD (Append to Existing Stories)
**Trigger:** Epic has Stories, user wants to ADD more (not replan existing)
**Delegation:**
Call ln-222-story-creator via Skill tool with appendMode:
```javascript
Skill(
skill: "ln-222-story-creator",
appendMode: true, // ADD to existing, don't replace
epicData: {id, title, description},
newStoryDescription: userRequestedStory, // Single Story from user request
standardsResearch: "Standards Research from Phase 2",
teamId: "team-id",
autoApprove: false
)
```
**Key differences from CREATE MODE:**
- `appendMode: true` → Skip full IDEAL plan, create only requested Story
- `newStoryDescription` → User's specific request (e.g., "add authorization Story")
- Does NOT require Phase 3 IDEAL plan for all Stories
- Preserves existing Stories without comparison
**Worker handles:**
- Research standards for NEW Story only
- Generate Story document (8 sections)
- Validate INVEST criteria
- Create in Linear (append to existing)
- Update kanban_board.md
**Output:** Created Story URL + summary from worker
---
## Integration with Ecosystem
**Calls:**
- **ln-221-standards-researcher** (Phase 2) - research standards/patterns for Epic
- **ln-222-story-creator** (Phase 5a, 5c) - CREATE and ADD worker
- **ln-223-story-replanner** (Phase 5b) - REPLAN worker
**Called by:**
- **ln-200-scope-decomposer** (Phase 3) - automated full decomposition (scope → Epics → Stories)
- **Manual** - user invokes for Epic Story creation/replanning
**Upstream:**
- **ln-210-epic-coordinator** - creates Epics (prerequisite for Story creation)
**Downstream:**
- **ln-310-story-decomposer** - creates implementation tasks for each Story
- **ln-320-story-validator** - validates Story structure/content
- **ln-330-story-executor** - orchestrates task execution for Story
---
## Definition of Done
**✅ Phase 1: Context Assembly Complete:**
- [ ] Team ID, Epic number, Next Story Number loaded from kanban_board.md
- [ ] Q1-Q6 extracted from Epic (Step 2)
- [ ] Frontend Research attempted if Q2/Q5 missing (Step 3)
- [ ] Fallback Search attempted for missing info (Step 4)
- [ ] User input requested if still missing (Step 5)
- [ ] Complete Story planning context assembled
**✅ Phase 2: Standards Research Complete:**
- [ ] Epic parsed for domain keywords
- [ ] ln-221-standards-researcher invoked with Epic description + Story domain
- [ ] Standards Research cached for workers
- [ ] OR Phase 2 skipped (trivial CRUD, no standards, explicit skip)
**✅ Phase 3: Planning Complete:**
- [ ] Epic Scope analyzed
- [ ] Optimal Story count determined (5-10 Stories)
- [ ] IDEAL Story plan created (titles, statements, core AC, ordering)
- [ ] Story Grouping Guidelines validated (vertical slicing)
- [ ] INVEST checklist validated for all Stories
**✅ Phase 4: Check Existing Complete:**
- [ ] Queried Linear for existing Stories (count only)
- [ ] Execution mode determined (CREATE or REPLAN)
**✅ Phase 5: Delegation Complete:**
- [ ] Called ln-222-story-creator (Phase 5a) OR ln-223-story-replanner (Phase 5b) via Skill tool
- [ ] Passed epicData, idealPlan, standardsResearch, teamId, autoApprove
- [ ] Received output from worker (Story URLs + summary + next steps)
---
## Example Usage
**CREATE MODE (First Time):**
```
"Create stories for Epic 7: OAuth Authentication"
```
**Process:**
1. Phase 1: Context Assembly → Discovery (Team "API", Epic 7, US004), Extract (Persona: API client, Value: secure API access), Frontend Research (HTML login/register forms → AC), Fallback Search (requirements.md for personas)
2. Phase 2: Standards Research → Epic mentions "OAuth 2.0", delegate ln-221 → Standards Research with RFC 6749, patterns
3. Phase 3: Planning → Build IDEAL (5 Stories: "Register client", "Request token", "Validate token", "Refresh token", "Revoke token")
4. Phase 4: Check Existing → Count = 0 → CREATE MODE
5. Phase 5a: Delegate CREATE → Call ln-222-story-creator → US004-US008 created with Standards Research
**REPLAN MODE (Requirements Changed):**
```
"Replan stories for Epic 7 - removed custom token formats, added scope management"
```
**Process:**
1. Phase 1: Context Assembly → Discovery (Team "API", Epic 7, has US004-US008), Extract (Removed custom formats, added scopes)
2. Phase 2: Standards Research → Epic mentions "OAuth 2.0 scopes", delegate ln-221 → Updated Standards Research with RFC 6749 Section 3.3
3. Phase 3: Planning → Build IDEAL (5 Stories: "Register client", "Request token", "Validate token", "Refresh token", "Manage scopes")
4. Phase 4: Check Existing → Count = 5 → REPLAN MODE
5. Phase 5b: Delegate REPLAN → Call ln-223-story-replanner → KEEP 4, UPDATE Technical Notes (scope research), OBSOLETE US008, CREATE US009
---
## Best Practices
**Story Content:**
- **Research-First:** Always perform Phase 2 research (standards/patterns) before Story generation
- **Story level:** STANDARDS/PATTERNS (OAuth RFC 6749, middleware pattern)
- **Task level:** LIBRARIES (authlib vs oauthlib) - delegated by ln-310
- **Business-oriented Stories:** Each Story = USER JOURNEY (what user does, what they get), NOT technical tasks
- ✅ GOOD: "As API client, I want to refresh expired token, so that I maintain session without re-authentication"
- ❌ BAD: "Create token refresh endpoint in API" (Task, not Story)
- **Vertical Slicing:** Each Story delivers end-to-end functionality (UI → API → Service → DB)
- **One capability per Story:** Clear, focused persona + capability + value
- **Testable AC:** Given-When-Then, 3-5 AC, specific criteria ("<200ms" not "fast")
- **Test Strategy:** Risk-Based Testing (2-5 E2E, 3-8 Integration, 5-15 Unit, 10-28 total)
- **Standards Research:** Include Phase 2 research in ALL Story Technical Notes
**Story Decomposition:**
- **Decompose-First:** Build IDEAL plan before checking existing - prevents anchoring to suboptimal structure
- **INVEST validation:** Validate every Story against INVEST criteria
- **Size enforcement:** 3-5 AC, 6-20 hours, 10-28 tests
- **Avoid over-decomposition:** <3 AC, <6 hours, <10 tests → Merge Stories
**User Interaction:**
- **Epic extraction:** Try to extract all planning info from Epic in Phase 1 Step 2 before asking user
- **Frontend Research:** HTML forms/validation → AC scenarios (Phase 1 Step 3)
- **Fallback search:** requirements.md, tech_stack.md if Epic incomplete (Phase 1 Step 4)
- **Only ask user for missing info** after Epic extraction AND frontend AND fallback search fail
**Delegation:**
- **Orchestrator loads metadata only:** ID, title, status (~50 tokens per Story)
- **Workers load full descriptions:** 8 sections (~5,000 tokens per Story)
- **Token efficiency:** 10 Stories × 50 tokens = 500 tokens (orchestrator) vs 10 Stories × 5,000 tokens = 50,000 tokens (workers load when needed)
---
**Version:** 4.0.0 (BREAKING: Decomposed to Orchestrator-Worker pattern. Phase 4a/4b removed, replaced with Phase 5a/5b delegation to ln-222-story-creator/ln-223-story-replanner. Orchestrator loads metadata only, workers load full descriptions for token efficiency. Progressive Loading now handled by ln-223-story-replanner, not orchestrator. Story execution logic moved to workers, orchestrator focuses on context assembly, standards research, planning, mode determination, delegation.)
**Last Updated:** 2025-11-20

170
skills/ln-220-story-coordinator/diagram.html Normal file
View File

@@ -0,0 +1,170 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>ln-220-story-coordinator Workflow</title>
<link rel="stylesheet" href="../shared/css/diagram.css">
<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
<script>
mermaid.initialize({
startOnLoad: true,
theme: 'base',
themeVariables: {
primaryColor: '#4A90E2',
primaryTextColor: '#fff',
primaryBorderColor: '#2E5C8A',
lineColor: '#5C6BC0',
secondaryColor: '#7E57C2',
tertiaryColor: '#26A69A'
}
});
</script>
</head>
<body>
<div class="container">
<h1>ln-220-story-coordinator: Story Coordinator</h1>
<div class="diagram-section">
<h2>Workflow Diagram</h2>
<div class="mermaid">
graph TD
Start([Input: Epic Number]) --> Phase1[Phase 1: Context Assembly]
Phase1 --> Step1Discovery[Step 1: Discovery<br/>Team ID, Epic, Story Number]
Step1Discovery --> Step2Extract[Step 2: Extract Planning Info<br/>Q1-Q6 from Epic]
Step2Extract --> CheckQ2Q5{Q2 or Q5<br/>missing?}
CheckQ2Q5 -->|Yes| Step3HTML[Step 3: Frontend Research<br/>Scan HTML for AC/capabilities]
CheckQ2Q5 -->|No| Step4Fallback
Step3HTML --> Step4Fallback[Step 4: Fallback Search<br/>requirements.md, tech_stack.md]
Step4Fallback --> CheckMissing{Still<br/>missing?}
CheckMissing -->|Yes| Step5User[Step 5: User Input<br/>Ask for remaining info]
CheckMissing -->|No| Phase2
Step5User --> Phase2[Phase 2: Standards Research]
Phase2 --> ParseDomains[Parse Epic for domain keywords<br/>standards mentions]
ParseDomains --> SkipResearch{Standards<br/>mentioned?}
SkipResearch -->|No| EmptyResearch[Empty Standards Research]
SkipResearch -->|Yes| DelegateLN221[DELEGATE: ln-221-standards-researcher<br/>epic_description, story_domain]
DelegateLN221 --> WaitResearch[Wait for Standards Research]
WaitResearch --> CacheResearch[Cache Standards Research<br/>for workers Phase 5a/5b]
EmptyResearch --> Phase3[Phase 3: Planning]
CacheResearch --> Phase3
Phase3 --> BuildIDEAL[Build IDEAL Plan "in mind"<br/>Analyze Scope, 5-10 Stories<br/>Vertical Slicing, INVEST Checklist]
BuildIDEAL --> Phase4[Phase 4: Check Existing]
Phase4 --> QueryLinear[Query Linear for existing Stories<br/>list_issues project=Epic label=user-story<br/>Metadata ONLY ID, title, status]
QueryLinear --> CountCheck{Count = 0?}
CountCheck -->|Yes| Phase5a[Phase 5a: Delegate CREATE]
CountCheck -->|No| Phase5b[Phase 5b: Delegate REPLAN]
Phase5a --> DelegateLN222[DELEGATE: ln-222-story-creator<br/>epicData, idealPlan<br/>standardsResearch, teamId<br/>autoApprove]
DelegateLN222 --> WaitCREATE[Wait for worker output:<br/>Created Story URLs<br/>Summary + Next Steps]
WaitCREATE --> End([Done])
Phase5b --> DelegateLN223[DELEGATE: ln-223-story-replanner<br/>epicData, idealPlan<br/>standardsResearch, existingCount<br/>teamId, autoApprove]
DelegateLN223 --> WaitREPLAN[Wait for worker output:<br/>Operation results<br/>Warnings + URLs + Next Steps]
WaitREPLAN --> End
style Start fill:#4A90E2,stroke:#2E5C8A,color:#fff
style End fill:#26A69A,stroke:#1B5E20,color:#fff
style Phase1 fill:#7E57C2,stroke:#4A148C,color:#fff
style Phase2 fill:#7E57C2,stroke:#4A148C,color:#fff
style Phase3 fill:#7E57C2,stroke:#4A148C,color:#fff
style Phase4 fill:#7E57C2,stroke:#4A148C,color:#fff
style Phase5a fill:#26A69A,stroke:#1B5E20,color:#fff
style Phase5b fill:#FF9800,stroke:#E65100,color:#fff
style CountCheck fill:#FF9800,stroke:#E65100,color:#fff
style SkipResearch fill:#FF9800,stroke:#E65100,color:#fff
style CheckQ2Q5 fill:#FF9800,stroke:#E65100,color:#fff
style CheckMissing fill:#FF9800,stroke:#E65100,color:#fff
style DelegateLN221 fill:#FFC107,stroke:#F57C00,color:#000
style DelegateLN222 fill:#FFC107,stroke:#F57C00,color:#000
style DelegateLN223 fill:#FFC107,stroke:#F57C00,color:#000
style WaitResearch fill:#FFC107,stroke:#F57C00,color:#000
style WaitCREATE fill:#FFC107,stroke:#F57C00,color:#000
style WaitREPLAN fill:#FFC107,stroke:#F57C00,color:#000
</div>
</div>
<div class="info-section">
<h2>Key Information</h2>
<ul>
<li><strong>Type:</strong> Domain Coordinator (L2)</li>
<li><strong>Phases:</strong> 5 phases (Context Assembly → Standards Research → Planning → Check Existing → Delegate)</li>
<li><strong>Pattern:</strong> Decompose-First (build IDEAL → check existing → CREATE/REPLAN)</li>
<li><strong>Delegates to:</strong> ln-221-standards-researcher (Phase 2), ln-222-story-creator (Phase 5a), ln-223-story-replanner (Phase 5b)</li>
<li><strong>Output:</strong> Worker output (5-10 Stories with Standards Research in Technical Notes)</li>
<li><strong>Modes:</strong> Phase 5a: Delegate CREATE (no existing) / Phase 5b: Delegate REPLAN (KEEP/UPDATE/OBSOLETE/CREATE)</li>
<li><strong>Version:</strong> 4.0.0 (BREAKING - Orchestrator-Worker pattern, Phase 5a/5b delegation)</li>
</ul>
</div>
<div class="delegation-section">
<h2>Delegation Flow</h2>
<ul>
<li><strong>Phase 2:</strong> ln-221-standards-researcher v2.0.0
<ul>
<li><strong>Input:</strong> Epic description + Story domain</li>
<li><strong>Output:</strong> Standards Research (RFCs, industry standards, architectural patterns)</li>
<li><strong>Time-box:</strong> 15-20 minutes</li>
</ul>
</li>
<li><strong>Phase 5a:</strong> ln-222-story-creator v1.0.0
<ul>
<li><strong>Input:</strong> epicData, idealPlan, standardsResearch, teamId, autoApprove</li>
<li><strong>Output:</strong> Created Story URLs + summary + next steps</li>
<li><strong>Handles:</strong> Generate documents, validate INVEST, create in Linear, update kanban</li>
</ul>
</li>
<li><strong>Phase 5b:</strong> ln-223-story-replanner v1.0.0
<ul>
<li><strong>Input:</strong> epicData, idealPlan, standardsResearch, existingCount, teamId, autoApprove</li>
<li><strong>Output:</strong> Operation results + warnings + affected URLs + next steps</li>
<li><strong>Handles:</strong> Load existing (Progressive Loading), compare, show diffs, execute operations, update kanban</li>
</ul>
</li>
</ul>
</div>
<div class="notes-section">
<h2>Important Notes</h2>
<ul>
<li><strong>Phase 1 (5 Steps):</strong> Context Assembly with Sequential Numbering
<ul>
<li>Step 1: Discovery (Team ID, Epic, Next Story Number from kanban_board.md)</li>
<li>Step 2: Extract Planning Info (Q1-Q6 from Epic Goal, Scope In/Out, Success Criteria)</li>
<li>Step 3: Frontend Research (Optional - scan HTML for AC/capabilities if Q2/Q5 missing)</li>
<li>Step 4: Fallback Search (requirements.md, tech_stack.md for missing Q1/Q3/Q6)</li>
<li>Step 5: User Input (Only if still missing after Step 2-4)</li>
</ul>
</li>
<li><strong>Phase 2:</strong> Standards Research - delegates to ln-221, caches for workers. Focus: RFCs, architectural patterns (NOT libraries)</li>
<li><strong>Phase 3:</strong> Planning - ALWAYS build IDEAL plan FIRST (5-10 vertical Stories), INVEST checklist. Story Grouping: 1 Story = 1 vertical slice (UI → API → DB)</li>
<li><strong>Phase 4:</strong> Check Existing - query Linear for metadata ONLY (ID, title, status ~50 tokens/Story). Workers load FULL descriptions (~5,000 tokens/Story) for token efficiency</li>
<li><strong>Phase 5a:</strong> Delegate CREATE - ln-222-story-creator handles document generation, INVEST validation, Linear creation, kanban update</li>
<li><strong>Phase 5b:</strong> Delegate REPLAN - ln-223-story-replanner handles Progressive Loading (ONE BY ONE), comparison, diffs (AC, Standards Research), Story Split/Merge warnings, operations execution</li>
<li><strong>Token Efficiency:</strong> Coordinator loads metadata only (~500 tokens for 10 Stories), workers load full descriptions when needed (~50,000 tokens)</li>
<li><strong>Story Numbering:</strong> No Story 0 reserved (Stories start from US001). Epic 0 = Infrastructure Epic (contains US001-US010)</li>
<li><strong>Epic Numbering:</strong> Epic N = Linear Project number (global), NOT initiative-internal index (Epic 0-N)</li>
</ul>
</div>
<div class="changes-section">
<h2>Changes in v4.0.0 (BREAKING)</h2>
<ul>
<li><strong>Orchestrator-Worker Pattern:</strong> Decomposed to coordinator + 2 workers (ln-222, ln-223)</li>
<li><strong>Phase 4a/4b Removed:</strong> Replaced with Phase 5a/5b delegation</li>
<li><strong>Coordinator loads metadata only:</strong> ID, title, status (~50 tokens/Story)</li>
<li><strong>Workers load full descriptions:</strong> 8 sections (~5,000 tokens/Story)</li>
<li><strong>Progressive Loading:</strong> Now handled by ln-223-story-replanner, not coordinator</li>
<li><strong>Story execution logic:</strong> Moved to workers (ln-222, ln-223)</li>
<li><strong>Coordinator focuses on:</strong> Context assembly, standards research, planning, mode determination, delegation</li>
<li><strong>Token Efficiency:</strong> 10 Stories: 500 tokens (coordinator) vs 50,000 tokens (workers load when needed)</li>
</ul>
</div>
</div>
</body>
</html>

506
skills/ln-220-story-coordinator/references/replan_algorithm.md Normal file
View File

@@ -0,0 +1,506 @@
# Story Replan Algorithm
Detailed documentation of the Story comparison and operation determination logic used in ln-220-story-coordinator REPLAN MODE.
## Overview
When ln-220-story-coordinator is invoked on an Epic that already has Stories, it enters REPLAN MODE. This algorithm determines how to reconcile the IDEAL Story plan (built from current Epic requirements) with existing Stories in Linear.
**Key Principle:** Decompose-First Pattern ensures we always build the IDEAL plan based on current Epic state BEFORE checking existing Stories, preventing "anchoring bias" to potentially outdated Story structure.
## Algorithm Steps
### Step 1: Match by Goal
**Objective:** Identify which existing Stories correspond to which Stories in IDEAL plan.
**Matching Criteria (Fuzzy Match):**
1. **Story Title Similarity:**
- Extract keywords from both titles
- Calculate similarity score (Levenshtein distance or keyword overlap)
- Match threshold: >70% similarity
2. **Persona Match:**
- Extract persona from Story Statement ("As a [persona]")
- Exact match required (e.g., "API client" matches "API client")
3. **Capability Match:**
- Extract capability from Story Statement ("I want [capability]")
- Fuzzy match on action verbs + objects
- Match threshold: >60% similarity
- Example: "register OAuth client" matches "create OAuth registration"
**Matching Process:**
```
For each Story in IDEAL plan:
For each existing Story:
Calculate similarity_score = (
0.4 * title_similarity +
0.3 * persona_match +
0.3 * capability_similarity
)
If similarity_score > 0.7:
Mark as MATCHED
```
**Output:**
- Matched pairs: (IDEAL Story, Existing Story)
- Unmatched IDEAL Stories → Candidates for CREATE
- Unmatched existing Stories → Candidates for OBSOLETE
### Step 2: Determine Operations
For each matched pair and unmatched Story, determine the appropriate operation.
#### KEEP Operation
**Criteria** (ALL must be true):
- ✅ Story exists in IDEAL plan (matched)
- ✅ Story Statement unchanged (persona + capability + value)
- ✅ AC unchanged (same Given-When-Then scenarios)
- ✅ Technical Notes still valid (no new integrations/patterns)
- ✅ Status: Any except Done or Canceled
**Action:** None (no Linear API calls)
**Example:**
```
IDEAL:
Title: US004: Register OAuth client
Persona: API client
Capability: Register new OAuth application
AC: [3 scenarios unchanged]
Existing:
Title: US004: Register OAuth client
Status: Todo
[Same Story Statement, AC, Technical Notes]
→ KEEP (no changes needed)
```
#### UPDATE Operation
**Criteria** (ANY must be true):
- ⚠️ AC changed (new AC added, existing modified, AC removed)
- ⚠️ Story Statement refined (same capability, clearer phrasing)
- ⚠️ Technical Notes changed (new guide links, integration approach)
- ⚠️ Test Strategy changed (different E2E/Integration/Unit distribution)
**Constraints:**
- Status: Backlog or Todo ONLY
- If In Progress/To Review/Done → Show warning, no auto-update
**Action:** `update_issue(id, description=new_description)`
**Example:**
```
IDEAL:
Title: US006: Validate access token
AC:
- Given token with valid signature, When validated, Then return claims
- Given token with invalid signature, When validated, Then reject
- Given expired token, When validated, Then return specific error ← NEW
Existing:
Title: US006: Validate access token
Status: Todo
AC: [Only first 2 scenarios]
→ UPDATE (new AC scenario added)
```
#### OBSOLETE Operation
**Criteria:**
- ❌ Story NOT in IDEAL plan (no match found)
- ❌ Feature removed from Epic Scope
- ❌ Capability no longer needed
**Constraints:**
- Status: Backlog or Todo ONLY
- If In Progress → Show warning "Story in progress, manual review needed"
- If To Review → Show warning "Story under review, manual review needed"
- If Done → Show warning "Story completed, cannot cancel - will remain in Epic"
**Action:** `update_issue(id, state="Canceled")`
**Rationale:** Use Canceled state (not deletion) to preserve history and reference.
**Example:**
```
Existing:
Title: US008: Custom token formats
Status: Todo
[Feature removed from Epic Scope]
IDEAL plan:
[No matching Story - custom formats feature removed]
→ OBSOLETE (cancel Story in Linear)
```
#### CREATE Operation
**Criteria:**
- ➕ Story in IDEAL plan (no match in existing)
- ➕ New capability added to Epic
- ➕ New user need identified
**Action:** `create_issue()` (same as CREATE MODE)
**Example:**
```
IDEAL:
Title: US009: Manage token scopes
Persona: API client
Capability: Define access scopes for tokens
[New Epic requirement]
Existing Stories:
[No matching Story - new capability]
→ CREATE (create new Story in Linear)
```
### Step 3: Handle Edge Cases
#### Case 1: Story In Progress with Changes
**Situation:** IDEAL plan shows AC changes for Story currently In Progress
**Resolution:**
- Do NOT auto-update (developers actively working on it)
- Show warning: "⚠️ US006 (In Progress): AC changed but cannot auto-update - manual review needed"
- Include diff in warning (show before/after AC)
- Recommend: Manual review after current work completes
**Example:**
```
IDEAL:
US006: New AC added (token expiry validation)
Existing:
US006: Status = In Progress (developer working on it)
→ WARNING (show diff, no auto-update)
```
#### Case 2: Story Done with Scope Changes
**Situation:** IDEAL plan shows Story should be removed, but it's already Done
**Resolution:**
- Do NOT cancel (work already completed and delivered)
- Show warning: "⚠️ US008 (Done): Feature removed from Epic scope, but Story already completed - will remain in Epic"
- Recommend: Keep for historical reference, do not revert
**Example:**
```
IDEAL:
[US008 not in plan - feature removed]
Existing:
US008: Status = Done
→ WARNING (cannot cancel Done Story)
```
#### Case 3: Multiple Matches (Ambiguous)
**Situation:** One IDEAL Story matches multiple existing Stories (similarity_score > 0.7 for multiple)
**Resolution:**
- Pick highest similarity_score match
- For other existing Stories → Mark as OBSOLETE candidates
- Show warning: "⚠️ Ambiguous match: US007 matches both 'Token refresh' and 'Token renewal' - selected 'Token refresh' (85% match)"
#### Case 4: No Matches (Complete Redesign)
**Situation:** Epic requirements completely changed, no existing Stories match IDEAL plan
**Resolution:**
- All existing Stories → OBSOLETE (if Backlog/Todo) or WARNING (if In Progress/Done)
- All IDEAL Stories → CREATE
- Show summary: "Complete Epic redesign detected: 5 Stories to obsolete, 7 new Stories to create"
- Require explicit user confirmation
#### Case 5: Story Split (1 → 2)
**Situation:** One existing Story matches 2 IDEAL Stories (capability split into smaller Stories)
**Resolution:**
- First IDEAL Story → UPDATE existing Story
- Second IDEAL Story → CREATE new Story
- Show explanation: "US004 'User authentication' split into US004 'Login' (update existing) and US009 'Password reset' (create new)"
#### Case 6: Story Merge (2 → 1)
**Situation:** Two existing Stories match 1 IDEAL Story (capabilities merged)
**Resolution:**
- Primary existing Story (higher similarity) → UPDATE
- Secondary existing Story → OBSOLETE
- Show explanation: "US004 'Login' and US005 'Session management' merged into US004 'User authentication' (update US004, obsolete US005)"
## Best Practices
### 1. Always Show Diffs
For UPDATE operations, show before/after comparison:
```
US006: Validate access token
Changes:
📋 Acceptance Criteria:
+ Given expired token, When validated, Then return specific error code
+ Given token from revoked client, When validated, Then reject
📝 Technical Notes:
+ Add guide link: Token Validation Best Practices
```
### 2. Group Operations by Type
Present operations in consistent order:
1. ✅ KEEP: N stories (list titles)
2. 🔧 UPDATE: M stories (show diffs)
3. ❌ OBSOLETE: K stories (show reasoning)
4. ➕ CREATE: L stories (show new capabilities)
5. ⚠️ WARNINGS: Edge cases requiring manual review
### 3. Preserve Story Continuity
- Keep existing Story IDs when updating (don't create new + delete old)
- Maintain Story numbering sequence (US004, US005, US006...)
- Update Epic Story Counters only for CREATE operations
### 4. Respect Status Transitions
Linear workflow:
```
Backlog → Todo → In Progress → To Review → Done
└─→ Canceled (OBSOLETE only)
```
**Safe to auto-update:** Backlog, Todo
**Warnings only:** In Progress, To Review, Done
### 5. Require User Confirmation
**Always** show complete summary before executing:
- Total operation count
- All diffs for UPDATE operations
- All warnings for edge cases
- Estimated impact (Stories affected)
**Never** execute operations without explicit "confirm" from user.
## Implementation Checklist
Before implementing replan in ln-220-story-coordinator, verify:
**✅ Data Loading:**
- [ ] Fetch all existing Stories from Epic: `list_issues(project=Epic.id, label="user-story")`
- [ ] Load FULL descriptions (all 8 sections) for each Story
- [ ] Note Story status (Backlog/Todo/In Progress/To Review/Done)
**✅ IDEAL Plan Building:**
- [ ] Build IDEAL plan from Epic Scope (Phase 4)
- [ ] IDEAL plan has 5-10 Stories
- [ ] Each IDEAL Story has: title, persona, capability, value, AC (3-5), Technical Notes
**✅ Matching:**
- [ ] Implement fuzzy matching (title + persona + capability)
- [ ] Similarity threshold: >70%
- [ ] Handle ambiguous matches (multiple existing match one IDEAL)
**✅ Operation Determination:**
- [ ] Implement KEEP logic (all unchanged)
- [ ] Implement UPDATE logic (AC/Tech changed, status=Backlog/Todo only)
- [ ] Implement OBSOLETE logic (not in IDEAL, status=Backlog/Todo only, use state="Canceled")
- [ ] Implement CREATE logic (new in IDEAL, no existing match)
**✅ Edge Cases:**
- [ ] Handle In Progress Stories with changes (warning, no auto-update)
- [ ] Handle Done Stories removed from Epic (warning, no cancel)
- [ ] Handle ambiguous matches (pick highest score, warn)
- [ ] Handle Story splits (UPDATE + CREATE)
- [ ] Handle Story merges (UPDATE + OBSOLETE)
**✅ User Experience:**
- [ ] Show grouped operations (KEEP/UPDATE/OBSOLETE/CREATE)
- [ ] Show diffs for UPDATE operations
- [ ] Show warnings with explanations
- [ ] Require explicit "confirm" before execution
- [ ] Show progress during execution ("Updating US006...")
- [ ] Show final summary (operations executed + warnings)
**✅ Linear API:**
- [ ] Use `update_issue(id, description)` for UPDATE
- [ ] Use `update_issue(id, state="Canceled")` for OBSOLETE
- [ ] Use `create_issue()` for CREATE
- [ ] Handle API errors gracefully
**✅ kanban_board.md:**
- [ ] Remove Canceled Stories from all sections
- [ ] Update modified Stories (keep in current section)
- [ ] Add new Stories to "### Backlog"
- [ ] Update Epic Story Counters (Last Story, Next Story)
## Scenarios
### Scenario 1: Minor AC Refinement
**Context:** Epic 7 OAuth Authentication, existing 5 Stories, refined AC for 2 Stories
**IDEAL Plan (5 Stories):**
- US004: Register OAuth client (unchanged)
- US005: Request access token (AC refined: add token expiry)
- US006: Validate token (AC refined: add signature validation details)
- US007: Refresh expired token (unchanged)
- US008: Revoke token (unchanged)
**Existing Stories (5 Stories):**
- US004: Register OAuth client (Backlog)
- US005: Request access token (Todo)
- US006: Validate token (In Progress)
- US007: Refresh expired token (Todo)
- US008: Revoke token (Backlog)
**Operations:**
- ✅ KEEP: US004, US007, US008 (3 Stories unchanged)
- 🔧 UPDATE: US005 (AC refined, status=Todo, safe to update)
- ⚠️ WARNING: US006 (AC refined, but status=In Progress, cannot auto-update)
**Summary:**
```
✅ KEEP: 3 stories unchanged
🔧 UPDATE: 1 story (US005)
⚠️ Manual Review Needed: 1 story
- US006 (In Progress): AC changed - review manually after current work completes
Operations: 1 update, 0 obsolete, 0 create
```
### Scenario 2: Feature Removed
**Context:** Epic 7, "Custom token formats" feature removed from scope
**IDEAL Plan (4 Stories):**
- US004: Register OAuth client
- US005: Request access token
- US006: Validate token
- US007: Refresh expired token
**Existing Stories (5 Stories):**
- US004: Register OAuth client (Todo)
- US005: Request access token (Todo)
- US006: Validate token (Done)
- US007: Refresh expired token (Todo)
- US008: Custom token formats (Todo)
**Operations:**
- ✅ KEEP: US004, US005, US006, US007 (4 Stories unchanged)
- ❌ OBSOLETE: US008 (feature removed, status=Todo, safe to cancel)
**Summary:**
```
✅ KEEP: 4 stories unchanged
❌ OBSOLETE: 1 story (US008 - Custom token formats)
Operations: 0 update, 1 obsolete, 0 create
```
### Scenario 3: New Feature Added
**Context:** Epic 7, "Token scope management" feature added to scope
**IDEAL Plan (6 Stories):**
- US004: Register OAuth client (unchanged)
- US005: Request access token (unchanged)
- US006: Validate token (unchanged)
- US007: Refresh expired token (unchanged)
- US008: Revoke token (unchanged)
- US009: Manage token scopes (NEW)
**Existing Stories (5 Stories):**
- US004: Register OAuth client (Backlog)
- US005: Request access token (Todo)
- US006: Validate token (Todo)
- US007: Refresh expired token (Todo)
- US008: Revoke token (Backlog)
**Operations:**
- ✅ KEEP: US004, US005, US006, US007, US008 (5 Stories unchanged)
- ➕ CREATE: US009 (new capability added)
**Summary:**
```
✅ KEEP: 5 stories unchanged
➕ CREATE: 1 new story (US009 - Manage token scopes)
Operations: 0 update, 0 obsolete, 1 create
```
### Scenario 4: Complete Epic Redesign
**Context:** Epic 7 scope completely changed from "OAuth Authentication" to "API Key Authentication"
**IDEAL Plan (4 Stories):**
- US009: Generate API key (NEW)
- US010: Validate API key (NEW)
- US011: Rotate API key (NEW)
- US012: Revoke API key (NEW)
**Existing Stories (5 Stories):**
- US004: Register OAuth client (Todo)
- US005: Request access token (Todo)
- US006: Validate token (In Progress)
- US007: Refresh expired token (Done)
- US008: Revoke token (Todo)
**Operations:**
- ❌ OBSOLETE: US004, US005, US008 (3 Stories, status=Todo, safe to cancel)
- ⚠️ WARNING: US006 (In Progress, cannot auto-cancel)
- ⚠️ WARNING: US007 (Done, cannot cancel)
- ➕ CREATE: US009, US010, US011, US012 (4 new Stories)
**Summary:**
```
Complete Epic redesign detected
❌ OBSOLETE: 3 stories (OAuth features removed)
⚠️ Manual Review Needed: 2 stories
- US006 (In Progress): Feature removed but work in progress - review manually
- US007 (Done): Feature removed but Story completed - will remain for historical reference
➕ CREATE: 4 new stories (API Key features)
Operations: 0 update, 3 obsolete, 4 create
⚠️ High impact - requires manual review of in-progress work
```
### Scenario 5: Story Split
**Context:** Epic 7, "User authentication" Story too large, split into "Login" and "Password reset"
**IDEAL Plan (6 Stories):**
- US004: Register OAuth client (unchanged)
- US005: User login (SPLIT from US006)
- US006: Request access token (unchanged from old US007)
- US007: Password reset (SPLIT from old US006)
- US008: Validate token (unchanged from old US008)
- US009: Refresh token (unchanged from old US009)
**Existing Stories (5 Stories):**
- US004: Register OAuth client (Todo)
- US006: User authentication (Todo, covers both login + password reset)
- US007: Request access token (Todo)
- US008: Validate token (Todo)
- US009: Refresh token (Todo)
**Operations:**
- ✅ KEEP: US004, US007, US008, US009 (4 Stories unchanged)
- 🔧 UPDATE: US006 → "User login" (narrow scope to just login)
- ➕ CREATE: US007 (new) → "Password reset" (split from US006)
**Summary:**
```
✅ KEEP: 4 stories unchanged
🔧 UPDATE: 1 story (US006 scope narrowed to "User login")
➕ CREATE: 1 new story (US007 - Password reset, split from US006)
Note: Story split detected - US006 "User authentication" → US006 "User login" + US007 "Password reset"
Operations: 1 update, 0 obsolete, 1 create
```
---
**Version:** 1.0.0 (Story replan algorithm with Epic extraction)
**Last Updated:** 2025-11-10

199
skills/ln-221-standards-researcher/SKILL.md Normal file
View File

@@ -0,0 +1,199 @@
---
name: ln-221-standards-researcher
description: Research standards/patterns via MCP Ref. Generates Standards Research for Story Technical Notes subsection. Reusable worker.
---
# Standards Researcher (Worker)
This skill researches industry standards and architectural patterns using MCP Ref to generate Standards Research for Story Technical Notes.
## When to Use This Skill
This skill should be used when:
- Need to research standards and patterns BEFORE Story generation (ensures tasks follow industry best practices)
- Epic Technical Notes mention specific standards requiring documentation (OAuth, OpenAPI, WebSocket)
- Prevent situations where tasks use outdated patterns or violate RFC compliance
- Reusable for ANY skill requiring standards research (ln-220-story-coordinator, ln-310-story-decomposer, ln-350-story-test-planner)
**Who calls this skill:**
- **ln-220-story-coordinator** (Phase 3) - research for Story creation
- **ln-310-story-decomposer** (optional) - research for complex Stories
- **ln-350-story-test-planner** (optional) - research for test task planning
- **Manual** - user can invoke directly for Epic/Story research
## How It Works
The skill follows a 5-phase workflow focused on standards and architectural patterns.
Phases: Identify → Ref Research → Existing Guides → Standards Research
### Phase 1: Identify Libraries
**Objective**: Parse Epic/Story for libraries and technology keywords.
**Process**:
1. **Read Epic/Story description** (provided as input)
- Parse Epic Technical Notes for mentioned libraries/frameworks
- Parse Epic Scope In for technology keywords (authentication, rate limiting, payments, etc.)
- Identify Story domain from Epic goal statement (e.g., "Add rate limiting" → domain = "rate limiting")
2. **Extract library list**:
- Primary libraries (explicitly mentioned)
- Inferred libraries (e.g., "REST API" → FastAPI, "caching" → Redis)
- Filter out well-known libraries with stable APIs (e.g., requests, urllib3)
3. **Determine Story domain**:
- Extract from Epic goal or Story title
- Examples: rate limiting, authentication, payment processing, file upload
**Output**: Library list (3-5 libraries max) + Story domain
**Skip conditions**:
- NO libraries mentioned in Epic → Output empty Research Summary
- Trivial CRUD operation with well-known libraries → Output empty Research Summary
- Epic explicitly states "research not needed" → Skip
---
### Phase 2: MCP Ref Research
**Objective**: Get industry standards and architectural patterns.
**Process:**
1. **Focus on standards/RFCs:**
- Call `mcp__Ref__ref_search_documentation(query="[story_domain] RFC standard specification")`
- Extract: RFC/spec references (OAuth 2.0 RFC 6749, OpenAPI 3.0, WebSocket RFC 6455)
2. **Focus on architectural patterns:**
- Call `mcp__Ref__ref_search_documentation(query="[story_domain] architectural patterns best practices")`
- Extract: Middleware, Dependency Injection, Decorator pattern
**Output:** Standards compliance table + Architectural patterns list
---
### Phase 3: MCP Ref Research
**Objective**: Get industry standards and best practices.
**Process**:
1. **FOR EACH library + Story domain** combination:
- Call `mcp__Ref__ref_search_documentation(query="[library] [domain] best practices 2025")`
- Call `mcp__Ref__ref_search_documentation(query="[domain] industry standards RFC")`
2. **Extract from results**:
- **Industry standards** (RFC/spec references: OAuth 2.0, REST API, OpenAPI 3.0, WebSocket)
- **Common patterns** (do/don't examples, anti-patterns to avoid)
- **Integration approaches** (middleware, dependency injection, decorators)
- **Security considerations** (OWASP compliance, vulnerability mitigation)
- **Best practices URLs** (link to authoritative sources)
3. **Store results** for Research Summary compilation
**Output**: Standards compliance table (RFC/Standard name, how to comply) + Best practices list
---
### Phase 4: Scan Existing Guides
**Objective**: Find relevant pattern guides in docs/guides/ directory.
**Process**:
1. **Scan guides directory**:
- Use `Glob` to find `docs/guides/*.md`
- Read guide filenames
2. **Match guides to Story domain**:
- Match keywords (e.g., rate limiting guide for rate limiting Story)
- Fuzzy match (e.g., "authentication" matches "auth.md", "oauth.md")
3. **Collect guide paths** for linking in Technical Notes
**Output**: Existing guides list (relative paths from project root)
---
### Phase 5: Generate Standards Research
**Objective**: Compile research results into Standards Research for Story Technical Notes subsection.
**Process:**
Generate Standards Research in Markdown format:
```markdown
## Standards Research
**Standards compliance:**
- [Standard/RFC name]: [how Story should comply - brief description]
- Example: "OAuth 2.0 (RFC 6749): Use authorization code flow with PKCE for public clients"
**Architectural patterns:**
- [Pattern name]: [when to use, why relevant for Story domain]
- Example: "Middleware pattern: Intercept requests for authentication before reaching endpoints"
**Existing guides:**
- [guide_path.md](guide_path.md) - [brief guide description]
```
**Return Standards Research** to calling skill (ln-220, ln-310, ln-350)
**Output:** Standards Research (Markdown string) for insertion into Story Technical Notes subsection
**Important notes:**
- Focus on STANDARDS and PATTERNS only (no library details - libraries researched at Task level)
- Prefer official docs and RFC standards over blog posts
- If Standards Research is empty (no standards/patterns) → Return "No standards research needed"
- Standards Research will be inserted in EVERY Story's Technical Notes (Standards Research subsection)
---
## Integration with Ecosystem
**Called by:**
- **ln-220-story-coordinator** (Phase 2) - research for ALL Stories in Epic
- **ln-310-story-decomposer** (optional) - research for complex technical Stories
- **ln-350-story-test-planner** (optional) - research for test infrastructure
**Dependencies:**
- MCP Ref (ref_search_documentation) - industry standards and patterns
- Glob (scan docs/guides/)
**Input parameters (from calling skill):**
- `epic_description` (string) - Epic Technical Notes + Scope In + Goal
- `story_domain` (string, optional) - Story domain (e.g., "rate limiting")
**Output format:**
- Markdown string (Standards Research for Technical Notes subsection)
- Format: Standards + Patterns (libraries researched at Task level)
---
## Time-Box and Performance
**Time-box:** 15-20 minutes maximum per Epic
**Performance:**
- Research is done ONCE per Epic
- Results reused for all Stories (5-10 Stories benefit from single research)
- Parallel MCP calls when possible (Context7 + Ref)
**Token efficiency:**
- Context7: max 3000 tokens per library
- Total: ~10,000 tokens for typical Epic (3-4 libraries)
---
## References
**Tools:**
- `mcp__Ref__ref_search_documentation()` - Search best practices and standards
- `Glob` - Scan docs/guides/ directory
**Templates:**
- [research_guidelines.md](references/research_guidelines.md) - Research quality guidelines (official docs > blog posts, prefer LTS versions)
---
**Version:** 2.0.0 (BREAKING: Renamed to ln-221-standards-researcher, removed research_level parameter, simplified to standards/patterns only)
**Last Updated:** 2025-11-20

118
skills/ln-221-standards-researcher/diagram.html Normal file
View File

@@ -0,0 +1,118 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>ln-221-library-researcher Workflow</title>
<link rel="stylesheet" href="../shared/css/diagram.css">
<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
<script>
mermaid.initialize({
startOnLoad: true,
theme: 'base',
themeVariables: {
primaryColor: '#4A90E2',
primaryTextColor: '#fff',
primaryBorderColor: '#2E5C8A',
lineColor: '#5C6BC0',
secondaryColor: '#7E57C2',
tertiaryColor: '#26A69A'
}
});
</script>
</head>
<body>
<div class="container">
<h1>ln-221-library-researcher: Library Researcher (Worker)</h1>
<div class="diagram-section">
<h2>Workflow Diagram</h2>
<div class="mermaid">
graph TD
Start([Input: Epic Description + Story Domain]) --> Phase1[Phase 1: Identify Libraries]
Phase1 --> Parse[Parse Epic Technical Notes<br/>+ Scope In + Goal]
Parse --> ExtractLibs[Extract Library List<br/>3-5 libraries max]
ExtractLibs --> Domain[Determine Story Domain<br/>e.g., rate limiting]
Domain --> SkipCheck{Libraries<br/>found?}
SkipCheck -->|No| EmptySummary[Output: Empty Research Summary]
SkipCheck -->|Yes| Phase2[Phase 2: MCP Context7 Research]
Phase2 --> LoopLibs[FOR EACH Library]
LoopLibs --> ResolveID[resolve-library-id<br/>libraryName]
ResolveID --> GetDocs[get-library-docs<br/>libraryID, topic, tokens=3000]
GetDocs --> ExtractAPI[Extract:<br/>- Latest version<br/>- Key APIs 2-5<br/>- Constraints<br/>- Deprecations]
ExtractAPI --> Fallback{Found in<br/>Context7?}
Fallback -->|No| WebSearch[Fallback: WebSearch<br/>library latest version API]
Fallback -->|Yes| Phase3[Phase 3: MCP Ref Research]
WebSearch --> Phase3
Phase3 --> RefSearch[ref_search_documentation<br/>library + domain best practices]
RefSearch --> RefStandards[ref_search_documentation<br/>domain standards RFC]
RefStandards --> ExtractStandards[Extract:<br/>- Industry standards<br/>- Common patterns<br/>- Security considerations<br/>- Integration approaches]
ExtractStandards --> Phase4[Phase 4: Scan Existing Guides]
Phase4 --> GlobGuides[Glob docs/guides/*.md]
GlobGuides --> MatchDomain[Match guides to Story domain<br/>fuzzy match]
MatchDomain --> CollectPaths[Collect guide paths]
CollectPaths --> Phase5[Phase 5: Generate Research Summary]
Phase5 --> CompileTable[Compile:<br/>- Library table version, purpose<br/>- Key APIs list<br/>- Constraints list<br/>- Standards compliance<br/>- Existing guides links]
CompileTable --> FormatMD[Format as Markdown]
FormatMD --> End([Output: Research Summary<br/>for Technical Notes])
EmptySummary --> End
style Start fill:#4A90E2,stroke:#2E5C8A,color:#fff
style End fill:#26A69A,stroke:#1B5E20,color:#fff
style Phase1 fill:#7E57C2,stroke:#4A148C,color:#fff
style Phase2 fill:#7E57C2,stroke:#4A148C,color:#fff
style Phase3 fill:#7E57C2,stroke:#4A148C,color:#fff
style Phase4 fill:#7E57C2,stroke:#4A148C,color:#fff
style Phase5 fill:#7E57C2,stroke:#4A148C,color:#fff
style SkipCheck fill:#FF9800,stroke:#E65100,color:#fff
style Fallback fill:#FF9800,stroke:#E65100,color:#fff
style WebSearch fill:#FFC107,stroke:#F57C00,color:#000
style EmptySummary fill:#9E9E9E,stroke:#424242,color:#fff
</div>
</div>
<div class="info-section">
<h2>Key Information</h2>
<ul>
<li><strong>Type:</strong> Worker (reusable)</li>
<li><strong>Phases:</strong> 5 (sequential workflow)</li>
<li><strong>Input:</strong> Epic description + Story domain</li>
<li><strong>Output:</strong> Research Summary (Markdown)</li>
<li><strong>Time-box:</strong> 15-20 minutes per Epic</li>
<li><strong>Token usage:</strong> ~10,000 tokens (3-4 libraries)</li>
<li><strong>Reusability:</strong> Called by ln-220, ln-310, ln-350</li>
</ul>
</div>
<div class="tools-section">
<h2>Tools Used</h2>
<ul>
<li><code>mcp__context7__resolve-library-id()</code> - Get library ID from name</li>
<li><code>mcp__context7__get-library-docs()</code> - Get latest API documentation (max 3000 tokens per library)</li>
<li><code>mcp__Ref__ref_search_documentation()</code> - Search best practices and industry standards</li>
<li><code>Glob</code> - Scan docs/guides/ directory for existing pattern guides</li>
<li><code>WebSearch</code> - Fallback for libraries not in Context7</li>
</ul>
</div>
<div class="notes-section">
<h2>Important Notes</h2>
<ul>
<li>Research done ONCE per Epic, results reused for all Stories (5-10 Stories benefit)</li>
<li>Focus on KEY APIs only (2-5 methods), not exhaustive documentation</li>
<li>Prefer official docs and RFC standards over blog posts</li>
<li>Skip research if NO libraries mentioned or trivial CRUD operation</li>
<li>Parallel MCP calls when possible (Context7 + Ref)</li>
</ul>
</div>
</div>
</body>
</html>

190
skills/ln-221-standards-researcher/references/research_guidelines.md Normal file
View File

@@ -0,0 +1,190 @@
# Research Guidelines
Quality guidelines for library and standards research to ensure accurate, up-to-date, and actionable information.
## Source Credibility Hierarchy
Use this priority order when selecting sources:
| Priority | Source Type | Example | When to Use |
|----------|-------------|---------|-------------|
| **1** | Official documentation | Python.org, FastAPI docs, RFC specifications | ALWAYS prefer official docs |
| **2** | Industry standards | RFC 6749 (OAuth), OpenAPI 3.0 spec, OWASP guidelines | For protocol/standard compliance |
| **3** | Vendor documentation | AWS docs, Redis docs, PostgreSQL docs | For specific vendor implementations |
| **4** | Community standards | PEP (Python), JSR (Java), WCAG (accessibility) | For language/platform best practices |
| **5** | Authoritative blogs | Real Python, DigitalOcean tutorials, vendor blogs | For complex integration examples |
| **6** | Stack Overflow | Accepted answers with high votes (500+) | LAST RESORT - verify info elsewhere |
**RED FLAGS (avoid):**
- Blog posts > 2 years old (outdated patterns)
- Personal blogs without credentials
- Medium posts without verification
- Reddit/forum posts (use for direction only)
---
## Version Selection Guidelines
| Scenario | Preferred Version | Rationale |
|----------|-------------------|-----------|
| **Production projects** | Latest LTS (Long Term Support) | Stability + security updates |
| **New features** | Latest stable release | Modern APIs, avoid beta/RC |
| **Legacy projects** | Match existing version (upgrade path in separate Story) | Avoid breaking changes |
| **Experimental** | Latest (including RC) | ONLY if Epic explicitly requests bleeding edge |
**Version notation:**
- ✅ GOOD: "v3.12.1 (LTS)" or "v2.5.0 (stable)"
- ❌ BAD: "latest" or "v3.x" (not specific)
**Deprecation check:**
- If library has deprecated methods → List in "Key constraints"
- If library is end-of-life → Suggest alternatives
---
## Key APIs Extraction
**Focus on 2-5 MOST RELEVANT methods for Story domain:**
### Good Example (rate limiting Story):
```
**Key APIs:**
- `Limiter(key_func=get_remote_address, default_limits=["200/day"])` - Initialize rate limiter with default limits
- `@limiter.limit("5/minute")` - Decorator for route-specific limits
- `limiter.reset()` - Reset limits programmatically (testing, admin operations)
```
### Bad Example (too generic):
```
**Key APIs:**
- Constructor
- Methods
- Properties
```
**Extraction rules:**
1. Include method signature (parameters, return type if critical)
2. Explain WHEN to use (not just WHAT it does)
3. Prioritize methods for Story domain (not all library methods)
4. If >5 methods → group by category (CRUD, validation, utilities)
---
## Constraints and Limitations
**MUST document:**
- Async/sync support (e.g., "slowapi v0.1.9 has NO async support")
- Storage backends (e.g., "in-memory storage doesn't persist across restarts")
- Multi-process caveats (e.g., "Limiter doesn't share state across workers without Redis")
- Platform limitations (e.g., "Windows async I/O has known issues")
- Performance limitations (e.g., "max 10K requests/sec without Redis backend")
**Format:**
```markdown
**Key constraints:**
- [Limitation]: [Brief explanation] - [Workaround or solution]
```
**Example:**
```markdown
**Key constraints:**
- No async support in v0.1.9 - Use slowapi v0.2.0+ OR sync endpoints only
- In-memory storage loses data on restart - Use Redis backend for production
- Rate limiting doesn't work across multiple workers - Configure Redis shared storage
```
---
## Standards Compliance
**Industry standards to check (by domain):**
| Domain | Relevant Standards |
|--------|-------------------|
| **Authentication** | OAuth 2.0 (RFC 6749), OpenID Connect, JWT (RFC 7519) |
| **REST API** | OpenAPI 3.0, REST principles (RFC 7231), HATEOAS |
| **Security** | OWASP Top 10, NIST guidelines, CSP (Content Security Policy) |
| **Data formats** | JSON Schema, Protocol Buffers, Avro |
| **Protocols** | HTTP/2 (RFC 7540), WebSocket (RFC 6455), gRPC |
| **Accessibility** | WCAG 2.1, ARIA, Section 508 |
**Format:**
```markdown
**Standards compliance:**
- [Standard/RFC name]: [How Story should comply - brief description]
```
**Example:**
```markdown
**Standards compliance:**
- RFC 6749 (OAuth 2.0): Use authorization code flow with PKCE for web apps
- OWASP Top 10 (2021): Implement rate limiting to prevent brute-force attacks (A07:2021)
- OpenAPI 3.0: Document rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset)
```
---
## Research Summary Template
```markdown
## Library Research
**Primary libraries:**
| Library | Version | Purpose | Docs |
|---------|---------|---------|------|
| slowapi | v0.2.1 (stable) | Rate limiting for FastAPI endpoints | [GitHub](https://github.com/laurentS/slowapi) |
| redis-py | v5.0.0 (stable) | Redis backend for distributed rate limiting | [Redis docs](https://redis.io/docs/clients/python/) |
**Key APIs:**
- `Limiter(key_func=get_remote_address, storage_uri="redis://localhost:6379")` - Initialize with Redis backend for multi-worker support
- `@limiter.limit("5/minute")` - Apply per-route rate limits (returns 429 on exceed)
- `@limiter.exempt` - Exempt specific routes (admin endpoints, health checks)
**Key constraints:**
- slowapi v0.1.9 has NO async support - Upgrade to v0.2.0+ for FastAPI async routes
- In-memory storage loses data on restart - Use Redis backend for production environments
- Rate limiting doesn't work across multiple workers without shared storage - Configure Redis URI
**Standards compliance:**
- RFC 6585 (HTTP 429): Return 429 Too Many Requests with Retry-After header
- OWASP A07:2021 (Identification/Auth Failures): Implement rate limiting on login endpoints (5 attempts/15 min)
- OpenAPI 3.0: Document rate limit response headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset)
**Existing guides:**
- [docs/guides/rate_limiting_pattern.md](docs/guides/rate_limiting_pattern.md) - Rate limiting best practices for FastAPI
```
---
## Time Management
**Time-box: 15-20 minutes maximum per Epic**
**Time allocation:**
- Phase 1 (Identify): 2-3 minutes
- Phase 2 (Context7): 5-7 minutes (parallel calls)
- Phase 3 (Ref): 5-7 minutes (parallel calls)
- Phase 4 (Guides): 1-2 minutes
- Phase 5 (Summary): 2-3 minutes
**If time exceeds:**
- Reduce library count (focus on 2-3 primary libraries)
- Skip fallback WebSearch
- Use cached Ref results from previous Epics
---
## Quality Checklist
Before returning Research Summary, verify:
- [ ] All libraries have specific versions (not "latest")
- [ ] Key APIs (2-5 methods) include when to use (not just what)
- [ ] Constraints list workarounds or solutions
- [ ] Standards compliance includes HOW to comply (not just standard name)
- [ ] Official docs URLs are valid (not broken links)
- [ ] Research Summary is ≤ 500 words (concise, actionable)
---
**Version:** 1.0.0
**Last Updated:** 2025-11-17

260
skills/ln-222-story-creator/SKILL.md Normal file
View File

@@ -0,0 +1,260 @@
---
name: ln-222-story-creator
description: Creates Stories from IDEAL plan (CREATE) or appends user-requested Stories (ADD). Generates 8-section documents, validates INVEST, creates in Linear. Invoked by ln-220.
---
# Story Creator
Universal factory worker for creating Stories. Supports two modes:
- **CREATE MODE**: Epic has no Stories → create from IDEAL plan (5-10 Stories)
- **ADD MODE**: Epic has Stories → append new Story(s) from user request
Invoked by ln-220-story-coordinator (Phase 5a for CREATE, Phase 5c for ADD).
## When Invoked
**1. ln-220-story-coordinator CREATE MODE (Phase 5a):**
- Epic has NO existing Stories (Linear query count = 0)
- IDEAL plan generated (Phase 3)
- Standards Research completed by ln-221 (Phase 2)
- Parameters: `epicData`, `idealPlan`, `standardsResearch`, `teamId`, `autoApprove`
**2. ln-220-story-coordinator ADD MODE (Phase 5c):**
- Epic HAS existing Stories, user wants to ADD more (not replan)
- Single Story or few Stories from user request
- Parameters: `epicData`, `appendMode: true`, `newStoryDescription`, `standardsResearch`, `teamId`
## Input Parameters
**For CREATE MODE (from ln-220-story-coordinator Phase 5a):**
```javascript
{
epicData: {id, title, description},
idealPlan: [
{
number: "US004",
title: "Register OAuth client",
statement: {persona, capability, value},
ac: [GWT scenarios],
technicalNotes: {architecture, integrations, performance},
estimatedHours: 12,
testCounts: {e2e: 2, integration: 5, unit: 11}
}
],
standardsResearch: "OAuth 2.0 (RFC 6749)...",
teamId: "team-id",
autoApprove: true
}
```
**For ADD MODE (from ln-220-story-coordinator Phase 5c with appendMode):**
```javascript
{
epicData: {id, title, description},
appendMode: true, // Signals ADD MODE - append to existing
newStoryDescription: "User's request for new Story",
standardsResearch: "Focused research for new Story only",
teamId: "team-id",
autoApprove: false // User confirmation recommended
}
```
- **appendMode**: `true` signals ADD MODE - append to existing Stories
- **newStoryDescription**: User's request for new Story(s) to add
- **NO idealPlan** - creates only what user requested (single Story or few)
## Workflow
> [!NOTE]
> **ADD MODE (appendMode: true)**: When adding Stories to existing Epic, workflow is simplified:
> - Phase 1: Generate only requested Story(s) from `newStoryDescription`
> - Skip full IDEAL plan comparison
> - Standards Research is focused only on new Story topics
> - Other phases proceed normally (INVEST, Preview, Create)
### Phase 1: Generate Story Documents
Read `references/story_template_universal.md` (8 sections).
For EACH Story in IDEAL plan:
| Section | Content |
|---------|---------|
| **1. Story Statement** | As a [persona] / I want [capability] / So that [value] |
| **2. Context** | Current Situation (from Epic Scope Out) / Desired Outcome (from Epic Success Criteria) |
| **3. AC** | Copy AC from idealPlan (3-5 GWT scenarios) |
| **4. Tasks** | Placeholder: "Tasks created via ln-310-story-decomposer after ln-320-story-validator" |
| **5. Test Strategy** | Copy test counts from idealPlan, Risk-Based Testing note |
| **6. Technical Notes** | **INSERT Standards Research** in Library Research subsection |
| **7. DoD** | Standard checklist from template |
| **8. Dependencies** | Empty OR "Depends On: US00X" if ordering implies dependency |
**Output:** Array of N complete Story documents (5-10) with Standards Research inserted.
### Phase 2: Validate INVEST
For EACH Story, check:
| Criterion | Check | Pass | Fail |
|-----------|-------|------|------|
| **Independent** | No circular dependencies | ✅ | ❌ STOP |
| **Negotiable** | AC focus on WHAT not HOW | ✅ | ❌ STOP |
| **Valuable** | Clear "So that" value | ✅ | ❌ STOP |
| **Estimable** | 6-20 hours | ✅ | ❌ STOP |
| **Small** | 3-5 AC, 10-28 tests | ✅ | ❌ STOP |
| **Testable** | Measurable AC (GWT format) | ✅ | ❌ STOP |
**Error if ANY Story fails** → Report to orchestrator, stop execution.
### Phase 3: Show Preview
```
STORY CREATION PREVIEW for Epic 7: OAuth Authentication
Will create 5 Stories:
1. US004: Register OAuth client
Persona: Third-party developer | Capability: Register app, get credentials
Value: Can integrate with API | AC: 4 | Estimate: 12h | Tests: 18
2. US005: Request access token
Persona: API client | Capability: Exchange credentials for token
Value: Authenticate to API | AC: 5 | Estimate: 18h | Tests: 24
... (3 more)
Total: 5 Stories, 62h, 90 tests
Standards Research: OAuth 2.0 (RFC 6749), RFC 7636 (PKCE), RFC 7009 (Revocation)
Story ordering: Dependency-aware (US004 → US005 → US006)
INVEST validation: ✓
Type "confirm" to create.
```
### Phase 4: User Confirmation
**If autoApprove=true:** Skip confirmation → Phase 5
**Otherwise:** Wait for "confirm"
### Phase 5: Create in Linear + Update Kanban
**Create Linear Issues:**
```javascript
for each Story:
create_issue({
title: Story.number + ": " + Story.title,
description: Story.generated_document,
project: epicData.id,
team: teamId,
labels: ["user-story"],
state: "Backlog"
})
```
**Update kanban_board.md:**
**Epic Grouping Algorithm:**
1. Find `### Backlog`
2. Search `**Epic {epicNumber}: {epicTitle}**`
- Found: use existing Epic group
- NOT found: create `**Epic N: Epic Title**`
3. Add Stories under Epic (2-space indent, 📖 emoji)
**Format:**
```markdown
**Epic 7: OAuth Authentication**
📖 [ID: US004 Register OAuth client](url)
_(tasks not created yet)_
📖 [ID: US005 Request access token](url)
_(tasks not created yet)_
```
**Update Epic Story Counters table:**
- Last Story: US008
- Next Story: US009
**Return:**
```
STORIES CREATED for Epic 7: OAuth Authentication
✓ Created 5 Stories in Linear:
1. [ID: US004 Register OAuth client](url)
2. [ID: US005 Request access token](url)
3. [ID: US006 Validate access token](url)
4. [ID: US007 Refresh expired token](url)
5. [ID: US008 Revoke token](url)
✓ kanban_board.md updated (Backlog + Epic Story Counters)
✓ Standards Research included: OAuth 2.0, RFC 7636 PKCE, RFC 7009 Revocation
Total: 5 Stories, 62h, 90 tests
NEXT STEPS:
1. Run ln-320-story-validator to validate Stories (Backlog → Todo)
2. Use ln-310-story-decomposer to create tasks
```
## Critical Rules
| Rule | Description |
|------|-------------|
| **Standards Research Insertion** | MUST insert in EVERY Story Technical Notes → Library Research |
| **INVEST Validation** | All Stories must pass before creation (stop if ANY fails) |
| **Template Ownership** | This skill owns story_template_universal.md in references/ |
| **Epic Grouping** | Reuse Epic header if exists (search by Epic number), don't duplicate |
| **Story Numbering** | Sequential across ALL Epics (read Next Story from kanban_board.md) |
| **No Code** | Descriptions contain approach ONLY, not code |
## Definition of Done
**✅ Phase 1:**
- [ ] All N Stories have 8 sections
- [ ] Standards Research inserted in Technical Notes → Library Research
**✅ Phase 2:**
- [ ] All Stories pass INVEST validation
**✅ Phase 3:**
- [ ] Preview shown (summaries, totals, Standards Research, ordering)
**✅ Phase 4:**
- [ ] autoApprove=true OR user confirmed
**✅ Phase 5:**
- [ ] All N Stories created in Linear (project=Epic, labels=user-story, state=Backlog)
- [ ] kanban_board.md updated (Backlog + Epic Story Counters)
- [ ] Summary returned (URLs + next steps)
## Reference Files
### story_template_universal.md
**Location:** `references/` (owned by this skill)
**Purpose:** Universal Story template (8 sections)
**Version:** 7.0.0
**Usage:** ln-223-story-replanner reads from ln-222/references/ for UPDATE/CREATE operations
## Integration
**Called by:** ln-220-story-coordinator
- Phase 5a (CREATE MODE, count = 0) - full IDEAL plan
- Phase 5c (ADD MODE, count ≥ 1, appendMode) - user-requested Story(s)
**Returns:**
- Success: Story URLs + summary + next steps
- Error: "Story USXXX violates INVEST: [details]"
**Worker does NOT:**
- Query Linear for Epic (already in context)
- Analyze Epic complexity (orchestrator Phase 3)
- Research standards (orchestrator Phase 2 delegates to ln-221)
- Build IDEAL plan (receives from orchestrator)
---
**Version:** 1.0.0
**Last Updated:** 2025-11-20

97
skills/ln-222-story-creator/diagram.html Normal file
View File

@@ -0,0 +1,97 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>ln-222-story-creator Workflow</title>
<link rel="stylesheet" href="../shared/css/diagram.css">
<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
<script>
mermaid.initialize({
startOnLoad: true,
theme: 'base',
themeVariables: {
primaryColor: '#4A90E2',
primaryTextColor: '#fff',
primaryBorderColor: '#2E5C8A',
lineColor: '#5C6BC0',
secondaryColor: '#7E57C2',
tertiaryColor: '#26A69A'
}
});
</script>
</head>
<body>
<div class="container">
<h1>ln-222-story-creator: Story Creator</h1>
<div class="diagram-section">
<h2>Workflow Diagram</h2>
<div class="mermaid">
graph TD
Start([Input: epicData, idealPlan, standardsResearch]) --> Phase1[Phase 1: Generate Story Documents]
Phase1 --> ReadTemplate[Read story_template_universal.md]
ReadTemplate --> GenerateDocs[For EACH Story in idealPlan:<br/>Generate 8 sections<br/>INSERT Standards Research]
GenerateDocs --> Phase2[Phase 2: Validate INVEST]
Phase2 --> ValidateAll[For EACH Story:<br/>Check I-N-V-E-S-T criteria]
ValidateAll --> CheckInvest{All pass?}
CheckInvest -->|No| Error[❌ STOP<br/>Report to orchestrator]
CheckInvest -->|Yes| Phase3[Phase 3: Show Preview]
Phase3 --> ShowPreview[Display:<br/>Story summaries<br/>Totals<br/>Standards Research<br/>INVEST: ✓]
ShowPreview --> Phase4[Phase 4: User Confirmation]
Phase4 --> CheckApprove{autoApprove?}
CheckApprove -->|true| Phase5
CheckApprove -->|false| WaitConfirm[Wait for 'confirm']
WaitConfirm --> Phase5[Phase 5: Create in Linear + Update Kanban]
Phase5 --> CreateLinear[For EACH Story:<br/>create_issue<br/>project=Epic, labels=user-story]
CreateLinear --> UpdateKanban[Update kanban_board.md:<br/>Epic Grouping Algorithm<br/>Update Epic Story Counters]
UpdateKanban --> Summary[Display Summary:<br/>URLs, Standards Research, Next Steps]
Summary --> End([Done])
style Start fill:#4A90E2,stroke:#2E5C8A,color:#fff
style End fill:#26A69A,stroke:#1B5E20,color:#fff
style Phase1 fill:#7E57C2,stroke:#4A148C,color:#fff
style Phase2 fill:#7E57C2,stroke:#4A148C,color:#fff
style Phase3 fill:#7E57C2,stroke:#4A148C,color:#fff
style Phase4 fill:#7E57C2,stroke:#4A148C,color:#fff
style Phase5 fill:#26A69A,stroke:#1B5E20,color:#fff
style Error fill:#F44336,stroke:#B71C1C,color:#fff
style CheckInvest fill:#FF9800,stroke:#E65100,color:#fff
style CheckApprove fill:#FF9800,stroke:#E65100,color:#fff
</div>
</div>
<div class="info-section">
<h2>Key Information</h2>
<ul>
<li><strong>Type:</strong> Worker (L3)</li>
<li><strong>Phases:</strong> 5 (Generate → Validate → Preview → Confirm → Create)</li>
<li><strong>Invoked by:</strong> ln-220-story-coordinator (Phase 5a, CREATE MODE)</li>
<li><strong>Input:</strong> epicData, idealPlan (5-10 Stories), standardsResearch, teamId, autoApprove</li>
<li><strong>Output:</strong> N Story URLs in Linear + kanban_board.md updated</li>
<li><strong>Validation:</strong> INVEST criteria (stop if ANY fails)</li>
<li><strong>Version:</strong> 1.0.0</li>
</ul>
</div>
<div class="notes-section">
<h2>Important Notes</h2>
<ul>
<li><strong>Phase 1:</strong> Generate 8-section Story documents for ALL Stories, INSERT Standards Research in Technical Notes → Library Research</li>
<li><strong>Phase 2:</strong> Validate INVEST (Independent, Negotiable, Valuable, Estimable, Small, Testable) for ALL Stories before creation</li>
<li><strong>Phase 3:</strong> Show preview with story summaries, totals (hours, tests), Standards Research included, INVEST validation passed</li>
<li><strong>Phase 4:</strong> autoApprove=true (automation mode) skips user confirmation, otherwise wait for "confirm"</li>
<li><strong>Phase 5:</strong> Create ALL Stories in Linear (project=Epic, labels=user-story, state=Backlog), update kanban_board.md with Epic Grouping Algorithm</li>
<li><strong>Standards Research:</strong> Inserted in EVERY Story (from ln-221-standards-researcher via ln-220 Phase 2), reused for consistency</li>
<li><strong>Epic Grouping:</strong> Reuse Epic header if exists (search by Epic number), don't duplicate</li>
<li><strong>Story Numbering:</strong> Sequential across ALL Epics (read Next Story from kanban_board.md Epic Story Counters)</li>
</ul>
</div>
</div>
</body>
</html>

195
skills/ln-222-story-creator/references/story_template_universal.md Normal file
View File

@@ -0,0 +1,195 @@
# US00N: Story Title
**Epic:** [Epic N - Epic Name](link-to-epic)
**Priority:** High | Medium | Low
---
## Story
**As a** [role/persona - e.g., API client, developer, end user]
**I want** [feature/capability - what they want to do]
**So that** [business value/benefit - why it matters]
---
## Context
### Current Situation
- What exists now?
- What's the pain point?
- Why is this needed?
### Desired Outcome
- What should exist after completion?
- How will this improve user experience?
- What business value delivered?
---
## Acceptance Criteria
Use **Given-When-Then** format:
### Main Scenarios
- **Given** [initial context/state]
**When** [action/event occurs]
**Then** [expected outcome/result]
- **Given** [context]
**When** [action]
**Then** [outcome]
- **Given** [context]
**When** [action]
**Then** [outcome]
### Edge Cases
- **Given** [edge case context]
**When** [edge case action]
**Then** [expected handling]
### Error Handling
- **Given** [error condition]
**When** [action attempted]
**Then** [expected error response]
---
## Implementation Tasks
Tasks created separately (parentId → this Story):
- [API-XX: Task Name](link) - Brief description
- [API-YY: Task Name](link) - Brief description
- [API-ZZ: Tests for Story](link) - **Final Task:** All tests (Unit/Integration/E2E)
> [!NOTE]
> Order tasks Consumer → Service → Provider (API endpoint → Service → Repository → Database). Consumer Tasks may mock provider layers until implemented.
---
## Test Strategy
> [!NOTE]
> All tests implemented in final Task of this Story (created by ln-350-story-test-planner after manual testing).
**Approach:** Risk-Based Testing with enforced limits (2-5 E2E, 3-8 Integration, 5-15 Unit per Story)
**Reference:** See `ln-350-story-test-planner/references/risk_based_testing_guide.md` for complete Risk-Based Testing methodology.
### E2E Tests (2-5 max)
Test complete user journeys. **ONLY Priority ≥15 scenarios** (money, security, core flows):
- [Critical AC or Edge Case]: [Priority score] - [Full business flow]
- [Critical AC or Edge Case]: [Priority score] - [Full business flow]
**Type:** API E2E / UI E2E (depending on application type)
**Based on:** ACTUAL manual testing results from ln-343-manual-tester (delegated by ln-340-story-quality-gate Pass 1)
### Integration Tests (3-8 max)
Test layer interactions with real dependencies. **ONLY Priority ≥15 interactions NOT covered by E2E:**
- [Integration Point]: [Priority score] - [What E2E doesn't cover: rollback/error/concurrency]
- [Integration Point]: [Priority score] - [What data flow to verify]
**Use Real:** Database (test), filesystem, internal services
**Use Mocks:** External APIs, payment systems, email services
### Unit Tests (5-15 max)
Test complex business logic in isolation. **ONLY Priority ≥15 logic NOT covered by E2E:**
- [Complex Function]: [Priority score] - [Financial calculation / Security logic / Algorithm]
- [Complex Function]: [Priority score] - [Edge cases from manual testing]
**SKIP:** Simple CRUD, framework code, trivial conditionals, getters/setters
**Test Limits:** 10-28 tests total per Story (enforced by ln-350-story-test-planner)
**Focus:** Critical path coverage (all Priority ≥15 scenarios), NOT coverage percentage
---
## Technical Notes
### Architecture Considerations
- Which layers affected? (API, Service, Repository, Client)
- What patterns apply?
- Any constraints?
### Library Research
**Primary libraries:**
| Library | Version | Purpose | Docs |
|---------|---------|---------|------|
| [name] | v[X.Y.Z] | [use case for Story domain] | [official docs URL] |
**Key APIs:**
- `[method_signature]` - [purpose and when to use]
- `[method_signature]` - [purpose and when to use]
**Key constraints:**
- [Constraint 1: e.g., no async support, memory limitations, multi-process caveats]
- [Constraint 2: e.g., compatibility requirements, deprecated features]
**Standards compliance:**
- [Standard/RFC]: [how Story complies - brief description, e.g., "RFC 6749 OAuth 2.0 - uses authorization code flow"]
> [!NOTE]
> This section populated by ln-220-story-coordinator Phase 0 (Library & Standards Research). Tasks reference these specifications in their Technical Approach sections.
### Integration Points
- **External Systems**: Which external APIs/services?
- **Internal Services**: Which app services interact?
- **Database**: Which tables/models involved?
### Performance & Security
- Response time targets
- Throughput requirements
- Security considerations
### Related Guides
- [Guide XX: Pattern Name](../guides/guide_XXX_pattern_name.md) - [when to use this pattern]
- [Guide YY: Pattern Name](../guides/guide_YYY_pattern_name.md) - [when to use this pattern]
> [!NOTE]
> Guide links inserted by ln-320-story-validator Phase 3 (auto-creates missing guides via ln-321-guide-creator, then links them here).
---
## Definition of Done
### Functionality
- [ ] All acceptance criteria met (main + edge cases + errors)
- [ ] Logging added appropriately
### Testing
- [ ] All implementation tasks completed (including final test task)
- [ ] All tests passing (E2E 2-5, Integration 3-8, Unit 5-15, total 10-28)
- [ ] All Priority ≥15 scenarios tested
### Code Quality
- [ ] Code reviewed and approved
- [ ] Follows project patterns
- [ ] Performance meets requirements
- [ ] Documentation updated
- [ ] All affected existing code refactored (no backward compatibility / legacy code left)
- [ ] All existing tests updated and passing
- [ ] All affected existing documentation updated
---
## Dependencies
### Depends On
- **User Story:** [USXXX](link) - Description
- **External:** Third-party requirement
### Blocks
- **User Story:** [USXXX](link) - Description
---
**Template Version:** 7.0.0 (Added Library Research + Related Guides subsections in Technical Notes)
**Last Updated:** 2025-11-12

273
skills/ln-223-story-replanner/SKILL.md Normal file
View File

@@ -0,0 +1,273 @@
---
name: ln-223-story-replanner
description: Replans Stories when Epic requirements change. Compares IDEAL vs existing, categorizes operations (KEEP/UPDATE/OBSOLETE/CREATE), executes in Linear.
---
# Story Replanner
Universal replanner worker for updating Stories in Epic when requirements change. Invoked by ln-220-story-coordinator (count ≥ 1).
## When Invoked
**ln-220-story-coordinator REPLAN MODE (Phase 5b):**
- Epic has existing Stories (Linear query count ≥ 1)
- IDEAL plan generated (Phase 3)
- Standards Research completed by ln-221 (Phase 2, may be updated)
- Epic requirements changed (AC modified, features added/removed, standards updated)
- Parameters: `epicData`, `idealPlan`, `standardsResearch`, `existingStoryIds`, `teamId`, `autoApprove`
## Input Parameters
**From ln-220-story-coordinator:**
```javascript
{
epicData: {id, title, description},
idealPlan: [{number, title, statement, ac, technicalNotes, estimatedHours, testCounts}],
standardsResearch: "OAuth 2.0 (RFC 6749)...", // May differ from existing
existingStoryIds: ["STORY-123", "STORY-124"], // Metadata only
teamId: "team-id",
autoApprove: true
}
```
## Workflow
### Phase 1: Load Existing Stories
**Progressive Loading for token efficiency:**
**Step 1:** Orchestrator provides Story metadata (ID, title, status)
**Step 2:** Load FULL descriptions ONE BY ONE
```javascript
for each story_id:
get_issue(id=story_id) // ~5,000 tokens per Story
```
**Token Rationale:** 10 Stories × 5,000 = 50,000 tokens. Load sequentially to manage context.
**Step 3:** Parse 8 sections for each Story
- Story Statement (persona, capability, value)
- Context
- Acceptance Criteria (3-5 GWT)
- Test Strategy
- Technical Notes (**Standards Research** in Library Research subsection)
- Definition of Done
- Dependencies
**Step 4:** Extract metadata
- ID, number, title, status
- Persona, capability, value
- AC scenarios
- Standards Research (from Technical Notes)
**Output:** Array of N existing Story structures ready for comparison.
### Phase 2: Compare IDEAL vs Existing
**Algorithm:** See [replan_algorithm_stories.md](references/replan_algorithm_stories.md)
**Match by goal, persona, capability:**
For EACH Story in IDEAL:
- Extract: Title, Persona, Capability
- Search existing: Fuzzy match title, check persona/capability overlap
- Result: Match → KEEP/UPDATE | No match → CREATE
For EACH existing Story:
- Extract: Title, Persona, Capability (from Story Statement)
- Search IDEAL: Fuzzy match
- Result: Match → KEEP/UPDATE | No match → OBSOLETE
**Categorize operations:**
| Operation | Criteria | Status Constraint | Action |
|-----------|----------|-------------------|--------|
| **KEEP** | Goal + Persona + Capability + AC + Standards Research same | Any | None |
| **UPDATE** | Match + (AC OR Standards Research OR Technical Notes changed) | Backlog/Todo ✅<br>In Progress/Review ⚠️<br>Done ❌ | `update_issue` |
| **OBSOLETE** | No match + Feature removed | Backlog/Todo ✅<br>In Progress/Review ⚠️<br>Done ❌ | `update_issue(state="Canceled")` |
| **CREATE** | In IDEAL + No match + New requirement | N/A | Generate doc + `create_issue` |
**Edge Cases:**
| Case | Action |
|------|--------|
| **In Progress OBSOLETE** | ⚠️ NO auto-cancel, show warning |
| **Done conflicts** | Preserve Done, CREATE follow-up |
| **Story Split** (1 → 2+) | ⚠️ UPDATE first + CREATE new |
| **Story Merge** (2+ → 1) | ⚠️ UPDATE first + OBSOLETE rest |
| **Ambiguous match** (>70% similarity) | Show all, select highest |
**Details:** [replan_algorithm_stories.md](references/replan_algorithm_stories.md)
### Phase 3: Show Operations Summary
```
REPLAN SUMMARY for Epic 7: OAuth Authentication
IDEAL PLAN:
1. US004: Register OAuth client (Persona: Third-party developer)
2. US005: Request access token ← AC5 ADDED! ← RFC 7636 PKCE ADDED!
3. US006: Validate access token
4. US009: Token scope management (NEW!)
EXISTING STORIES:
✓ US004 - Status: Done - KEEP
⚠ US005 - Status: Todo - UPDATE
Changes: Add AC5, Add RFC 7636 to Technical Notes, Add 2 Integration tests
Diff (AC): + AC5 "Given public client, When request with PKCE..."
Diff (Technical Notes): + RFC 7636 (PKCE)
✗ US008 - Status: Todo - OBSOLETE (feature removed)
+ US009 - NEW (14h, 20 tests, OAuth 2.0 Scope standard)
OPERATIONS: 2 keep, 1 update, 1 cancel, 1 create
WARNINGS:
- ⚠️ US005 (Todo): AC changed, Standards Research updated
- ⚠️ US008 (Todo): Feature removed - check dependencies
Type "confirm" to execute.
```
**Diffs show:**
- AC changes (line-by-line)
- Standards Research changes (added/removed RFCs)
- Test Strategy changes (test counts)
**Warnings for:**
- Status conflicts (In Progress/Review affected)
- Story Split/Merge detected
- Ambiguous matches
### Phase 4: User Confirmation
**If autoApprove=true:** Skip → Phase 5
**Otherwise:** Wait for "confirm"
**Adjustment:** User can request changes → Recategorize → Show updated summary → Loop until "confirm"
### Phase 5: Execute Operations
**Sequence:** UPDATE → OBSOLETE → CREATE → Update kanban
**UPDATE operations:**
1. Generate new Story document (story_template_universal.md from ln-222/references/)
2. Validate INVEST (same as ln-222-story-creator Phase 2)
3. `update_issue(id, description=new_description)`
4. Add comment: "Story updated: AC changed (AC5 added), Standards Research updated (RFC 7636)"
**OBSOLETE operations:**
1. `update_issue(id, state="Canceled")`
2. Add comment: "Story canceled: Feature removed from Epic Scope In. Reason: [details]"
**CREATE operations:**
1. Generate Story document (same as ln-222-story-creator Phase 1)
2. Validate INVEST
3. `create_issue({title, description, project=Epic, team, labels=["user-story"], state="Backlog"})`
**Update kanban_board.md:**
**DELETE (OBSOLETE):** Remove canceled Story lines, remove task lines if any, remove Epic header if empty
**CREATE (NEW):** Find `### Backlog` → Search Epic group → Add Stories (2-space indent)
**UPDATE Epic Story Counters:** Last Story, Next Story
**Return:**
```
REPLAN EXECUTED for Epic 7
OPERATIONS SUMMARY:
✓ Kept: 2 Stories
✓ Updated: 1 Story (AC/Standards Research changed)
✓ Canceled: 1 Story (feature removed)
✓ Created: 1 Story (new requirement)
UPDATED: [ID: US005](url) - AC5 added, RFC 7636 PKCE added
CANCELED: US008 Custom token formats
NEW: [ID: US009](url) - Token scope management
WARNINGS: US005 (Todo) AC changed
✓ kanban_board.md updated
✓ Standards Research updates: RFC 7636 PKCE added to US005
NEXT STEPS:
1. Review warnings
2. Run ln-320-story-validator on updated/created Stories
3. Use ln-310-story-decomposer to create/replan tasks
```
## Critical Rules
| Rule | Description |
|------|-------------|
| **Status Constraints** | UPDATE/OBSOLETE: Backlog/Todo ✅, In Progress/Review ⚠️, Done ❌ |
| **Preserve Done** | Never update/cancel Done Stories (CREATE follow-up if conflicts) |
| **Story Split/Merge** | Detect 1→2+ OR 2+→1, show warnings (complex, impacts Tasks) |
| **Clear Diffs** | Show before/after for UPDATE (AC, Standards Research, Technical Notes) |
| **Meaningful Comments** | Explain why updated/canceled (reference removed capabilities) |
| **Conservative Updates** | Prefer CREATE over UPDATE when in doubt |
| **Progressive Loading** | Load Stories ONE BY ONE (not all at once, token efficiency) |
## Definition of Done
**✅ Phase 1:**
- [ ] Existing Story IDs queried
- [ ] FULL descriptions fetched ONE BY ONE
- [ ] 8 sections parsed
- [ ] Metadata extracted (persona, capability, AC, Standards Research)
**✅ Phase 2:**
- [ ] Stories matched by goal/persona/capability
- [ ] Operations categorized (KEEP/UPDATE/OBSOLETE/CREATE)
- [ ] Edge cases detected (Split/Merge, Ambiguous)
**✅ Phase 3:**
- [ ] Operations summary shown
- [ ] Diffs shown for UPDATE (AC, Standards Research, Technical Notes)
- [ ] Warnings shown
**✅ Phase 4:**
- [ ] autoApprove=true OR user confirmed
**✅ Phase 5:**
- [ ] All operations executed (UPDATE/OBSOLETE/CREATE)
- [ ] kanban_board.md updated
- [ ] Summary returned (URLs + warnings)
## Reference Files
### replan_algorithm_stories.md
**Location:** `references/` (owned by this skill)
**Purpose:** Detailed comparison logic for REPLAN mode (Story level)
**Contents:** KEEP/UPDATE/OBSOLETE/CREATE rules, Match criteria, Status constraints, Edge cases, Examples
**Usage:** Applied in Phase 2
### story_template_universal.md
**Location:** `ln-222-story-creator/references/` (ln-222 ownership)
**Purpose:** Universal Story template (8 sections)
**Usage:** Read when generating updated Story documents for UPDATE/CREATE operations
## Integration
**Called by:** ln-220-story-coordinator (Phase 5b, count ≥ 1)
**Returns:**
- Success: Operations summary + URLs + warnings
- Error: "Story USXXX violates INVEST: [details]"
**Worker does NOT:**
- Query Linear for Epic (already in context)
- Analyze Epic complexity (orchestrator Phase 3)
- Research standards (orchestrator Phase 2)
- Build IDEAL plan (receives from orchestrator)
---
**Version:** 1.0.0
**Last Updated:** 2025-11-20

111
skills/ln-223-story-replanner/diagram.html Normal file
View File

@@ -0,0 +1,111 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>ln-223-story-replanner Workflow</title>
<link rel="stylesheet" href="../shared/css/diagram.css">
<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
<script>
mermaid.initialize({
startOnLoad: true,
theme: 'base',
themeVariables: {
primaryColor: '#4A90E2',
primaryTextColor: '#fff',
primaryBorderColor: '#2E5C8A',
lineColor: '#5C6BC0',
secondaryColor: '#7E57C2',
tertiaryColor: '#26A69A'
}
});
</script>
</head>
<body>
<div class="container">
<h1>ln-223-story-replanner: Story Replanner</h1>
<div class="diagram-section">
<h2>Workflow Diagram</h2>
<div class="mermaid">
graph TD
Start([Input: epicData, idealPlan, standardsResearch, existingCount]) --> Phase1[Phase 1: Load Existing Stories]
Phase1 --> LoadLoop[Progressive Loading:<br/>For EACH Story ONE BY ONE<br/>get_issue with full description]
LoadLoop --> Phase2[Phase 2: Compare IDEAL vs Existing]
Phase2 --> CompareAll[Match IDEAL to Existing<br/>Fuzzy match: title, persona, capability]
CompareAll --> Categorize[Categorize Operations:<br/>KEEP, UPDATE, OBSOLETE, CREATE]
Categorize --> CheckEdge{Edge cases?}
CheckEdge -->|Split/Merge| DetectComplex[⚠️ Story Split 1→2+<br/>⚠️ Story Merge 2+→1]
CheckEdge -->|Status conflicts| CheckStatus[⚠️ In Progress/Review<br/>❌ Done]
CheckEdge -->|No| Phase3[Phase 3: Show Replan Summary]
DetectComplex --> Phase3
CheckStatus --> Phase3
Phase3 --> ShowSummary[Display:<br/>IDEAL Plan changes<br/>Operations breakdown<br/>Diffs AC/Standards Research<br/>Warnings status/splits/merges]
ShowSummary --> Phase4[Phase 4: User Confirmation]
Phase4 --> CheckApprove{autoApprove?}
CheckApprove -->|true| Phase5
CheckApprove -->|false| WaitConfirm[Wait for 'confirm']
WaitConfirm --> Phase5[Phase 5: Execute Operations]
Phase5 --> ExecKeep[KEEP: Skip N Stories unchanged]
Phase5 --> ExecUpdate[UPDATE: update_issue<br/>new description Backlog/Todo only]
Phase5 --> ExecObsolete[OBSOLETE: update_issue<br/>state=Canceled + comment Backlog/Todo]
Phase5 --> ExecCreate[CREATE: Generate doc<br/>create_issue project=Epic labels=user-story]
ExecKeep --> UpdateKanban[Update kanban_board.md:<br/>Add NEW Stories ONLY<br/>Epic Grouping Algorithm<br/>Update Epic Story Counters]
ExecUpdate --> UpdateKanban
ExecObsolete --> UpdateKanban
ExecCreate --> UpdateKanban
UpdateKanban --> Summary[Display Summary:<br/>Operations executed<br/>URLs Warnings<br/>Next Steps]
Summary --> End([Done])
style Start fill:#4A90E2,stroke:#2E5C8A,color:#fff
style End fill:#26A69A,stroke:#1B5E20,color:#fff
style Phase1 fill:#7E57C2,stroke:#4A148C,color:#fff
style Phase2 fill:#7E57C2,stroke:#4A148C,color:#fff
style Phase3 fill:#7E57C2,stroke:#4A148C,color:#fff
style Phase4 fill:#7E57C2,stroke:#4A148C,color:#fff
style Phase5 fill:#26A69A,stroke:#1B5E20,color:#fff
style CheckEdge fill:#FF9800,stroke:#E65100,color:#fff
style CheckApprove fill:#FF9800,stroke:#E65100,color:#fff
style DetectComplex fill:#F44336,stroke:#B71C1C,color:#fff
style CheckStatus fill:#F44336,stroke:#B71C1C,color:#fff
</div>
</div>
<div class="info-section">
<h2>Key Information</h2>
<ul>
<li><strong>Type:</strong> Worker (L3)</li>
<li><strong>Phases:</strong> 5 (Load → Compare → Summary → Confirm → Execute)</li>
<li><strong>Invoked by:</strong> ln-220-story-coordinator (Phase 5b, REPLAN MODE)</li>
<li><strong>Input:</strong> epicData, idealPlan (5-10 Stories), standardsResearch, existingCount ≥1, teamId, autoApprove</li>
<li><strong>Output:</strong> Operations executed (KEEP/UPDATE/OBSOLETE/CREATE) + kanban_board.md updated</li>
<li><strong>Edge Cases:</strong> Story Split (1→2+), Story Merge (2+→1), Status conflicts (In Progress/Review/Done)</li>
<li><strong>Version:</strong> 1.0.0</li>
</ul>
</div>
<div class="notes-section">
<h2>Important Notes</h2>
<ul>
<li><strong>Phase 1:</strong> Progressive Loading - load existing Stories ONE BY ONE with FULL descriptions (token efficiency: 10 Stories × 5,000 tokens = 50,000 tokens)</li>
<li><strong>Phase 2:</strong> Match IDEAL to existing via fuzzy match (title, persona, capability), categorize KEEP/UPDATE/OBSOLETE/CREATE, detect Story Split (1→2+), Story Merge (2+→1)</li>
<li><strong>Phase 3:</strong> Show replan summary with IDEAL Plan changes, operations breakdown (N keep, N update, N cancel, N create), diffs (AC, Standards Research), warnings (status conflicts, splits, merges)</li>
<li><strong>Phase 4:</strong> autoApprove=true (automation mode) skips user confirmation, otherwise wait for "confirm"</li>
<li><strong>Phase 5:</strong> Execute operations - UPDATE/OBSOLETE only Backlog/Todo (warnings for In Progress/Review, never touch Done), CREATE new Stories (project=Epic, labels=user-story, state=Backlog), update kanban_board.md (add NEW Stories ONLY via Epic Grouping Algorithm)</li>
<li><strong>Status Constraints:</strong> UPDATE/OBSOLETE allowed for Backlog/Todo ✅, warnings for In Progress/Review ⚠️, never touch Done ❌ (preserve work, create follow-up Stories instead)</li>
<li><strong>Standards Research:</strong> UPDATE Stories when Epic standards change (new RFCs added/removed), insert updated research in Technical Notes → Library Research (Backlog/Todo only)</li>
<li><strong>Story Split Detection:</strong> 1 existing → 2+ IDEAL (same persona, split capabilities) → UPDATE first + CREATE new with warnings</li>
<li><strong>Story Merge Detection:</strong> 2+ existing → 1 IDEAL (combined capabilities) → UPDATE first + OBSOLETE rest with warnings</li>
</ul>
</div>
</div>
</body>
</html>

176
skills/ln-223-story-replanner/references/replan_algorithm_stories.md Normal file
View File

@@ -0,0 +1,176 @@
# Story Replan Algorithm
Comparison logic for ln-223-story-replanner REPLAN MODE. Determines operations (KEEP/UPDATE/OBSOLETE/CREATE) when existing Stories found for Epic.
## Overview
**Key Principle:** IDEAL plan (from ln-220 Phase 3) = source of truth. Compare existing Stories against IDEAL.
**Inputs:**
- IDEAL Story Plan: 5-10 Stories, vertical slices, AC 3-5 each, Standards Research from ln-221
- Existing Stories: Linear issues (Story Statement, AC, Technical Notes with Standards Research, status)
## Comparison Algorithm
### Match Criteria
**For EACH Story in IDEAL:**
- Extract: Title, Persona, Capability, Value
- Search existing: Fuzzy match title, check persona overlap, check capability overlap
- Result: Match found → KEEP/UPDATE candidate | No match → CREATE
**For EACH existing Story:**
- Extract: Title, Persona, Capability, Value (from Story Statement)
- Search IDEAL: Fuzzy match
- Result: Match found → KEEP/UPDATE candidate | No match → OBSOLETE
### Operations Matrix
| Operation | Criteria | Status Constraint | Action |
|-----------|----------|-------------------|--------|
| **KEEP** | Goal match + Persona same + Capability same + AC same + Standards Research same | Any | None |
| **UPDATE** | Goal match + (AC changed OR Standards Research changed OR Technical Notes changed) | Backlog/Todo ✅<br>In Progress/Review ⚠️<br>Done ❌ | `update_issue(description)` |
| **OBSOLETE** | No goal match + Feature removed from Epic Scope In | Backlog/Todo ✅<br>In Progress/Review ⚠️<br>Done ❌ | `update_issue(state="Canceled")` + comment |
| **CREATE** | In IDEAL + No existing match + New Epic requirement | N/A | Generate doc + `create_issue()` |
### Edge Cases
| Case | Condition | Action |
|------|-----------|--------|
| **In Progress OBSOLETE** | Story not in IDEAL + status In Progress/Review | ⚠️ NO auto-cancel, show warning |
| **Done conflicts** | IDEAL differs from Done Stories | Preserve Done, CREATE follow-up |
| **Story Split** | 1 existing → 2+ IDEAL (same persona, split capabilities) | ⚠️ UPDATE first + CREATE new |
| **Story Merge** | 2+ existing → 1 IDEAL (combined capabilities) | ⚠️ UPDATE first + OBSOLETE rest |
| **Ambiguous match** | >1 existing matches IDEAL (>70% similarity) | Show all, select highest |
| **Standards Research changed** | Epic standards updated (new RFCs added/removed) | UPDATE all affected Stories (Backlog/Todo only) |
## Example Scenarios
### Scenario 1: AC + Standards Research Update
**Change:** AC5 "PKCE flow" added to US005, RFC 7636 added to Epic
**IDEAL:** US005 (AC1-AC5, OAuth 2.0 + RFC 7636 PKCE)
**Existing:** US005 (AC1-AC4, OAuth 2.0 ONLY)
**Operation:** UPDATE US005
- Add AC5: "Given public client, When request token with PKCE, Then validate code_challenge"
- Update Technical Notes → Library Research: Add RFC 7636 (PKCE)
- Update Test Strategy: Add 2 Integration tests
### Scenario 2: Feature Removed
**Change:** Custom token formats removed from Epic Scope In
**IDEAL:** 5 Stories (US004-US008, standard OAuth 2.0 only)
**Existing:** 6 Stories (US004-US009, US009 = custom tokens)
**Operation:** OBSOLETE US009
- Comment: "Custom token formats removed from Epic Scope In per Epic v2.0.0. Simplified to standard OAuth 2.0 only."
### Scenario 3: New Story Added
**Change:** NEW capability "Token scope management" added to Epic
**IDEAL:** 6 Stories (US004-US009, US009 = token scopes NEW)
**Existing:** 5 Stories (US004-US008)
**Operation:** CREATE US009
- Persona: API client
- Capability: Request tokens with specific scopes (read, write, admin)
- AC: 4 scenarios
- Standards Research: OAuth 2.0 Scope (RFC 6749 Section 3.3)
### Scenario 4: Story Split (1 → 2+)
**Change:** US004 "User authentication" split into 3 focused Stories
**IDEAL:** US004 "Login" + US005 "Password reset" + US006 "Session"
**Existing:** US004 "User authentication" (AC1-AC9: login + password + session)
**Detection:** US004 existing matches US004 IDEAL (70%), US005 IDEAL (60%), US006 IDEAL (55%)
**Operations:**
- UPDATE US004: Narrow to "Login" only (keep AC1-AC3, remove AC4-AC9)
- CREATE US005: "Password reset" (AC4-AC6 from old US004)
- CREATE US006: "Session management" (AC7-AC9 from old US004)
⚠️ Warning: "Story Split detected: US004 'User authentication' → US004 'Login' (update) + US005 'Password reset' (create) + US006 'Session management' (create)"
### Scenario 5: Story Merge (2+ → 1)
**Change:** US004 "Product list" + US005 "Product search" merged into US004 "Product catalog"
**IDEAL:** US004 "Product catalog" (list + search combined)
**Existing:** US004 "Product list" (AC1-AC3) + US005 "Product search" (AC4-AC6)
**Detection:** (US004 + US005 existing) matches US004 IDEAL (85% similarity)
**Operations:**
- UPDATE US004: Expand to "Product catalog" (add AC4-AC6 from US005)
- OBSOLETE US005: Comment "Merged into US004 Product catalog for vertical slicing"
⚠️ Warning: "Story Merge detected: US004 'Product list' + US005 'Product search' → US004 'Product catalog' (update US004, obsolete US005)"
## Status Constraints
| Status | UPDATE | OBSOLETE |
|--------|--------|----------|
| **Backlog/Todo** | ✅ Allowed | ✅ Allowed |
| **In Progress/To Review** | ⚠️ Warning, manual review | ⚠️ Warning, manual review |
| **Done** | ❌ Never (preserve work) | ❌ Never (preserve history) |
**Done Story conflicts:** Keep Done, CREATE follow-up Story to address discrepancy.
Example: Done US005 "Request token" (without PKCE) + IDEAL "Request token with PKCE" → KEEP US005, CREATE US010 "Add PKCE support"
## Best Practices
| Practice | Rationale |
|----------|-----------|
| **Conservative Updates** | Prefer CREATE over UPDATE when in doubt (preserves existing work) |
| **Respect Status** | Never auto-update/cancel In Progress/Review/Done Stories |
| **Preserve History** | Use state="Canceled" for obsolete Stories (don't delete) |
| **Clear Diffs** | Show before/after for UPDATE (AC, Standards Research, Technical Notes) |
| **Meaningful Comments** | Explain why canceled (reference removed capabilities, reason) |
| **Split/Merge Detection** | Show warnings for structural changes (complex, impacts Tasks) |
| **Vertical Slicing** | Ensure IDEAL plan uses vertical slices (complete user journeys) |
| **Standards Consistency** | UPDATE all affected Stories when Epic standards change (Backlog/Todo only) |
## Output Format
```
REPLAN SUMMARY for Epic 7: OAuth Authentication
IDEAL PLAN:
1. US004: Register OAuth client (Persona: Third-party developer)
2. US005: Request access token ← AC5 ADDED! ← RFC 7636 PKCE ADDED!
3. US006: Validate access token
4. US007: Refresh expired token
5. US009: Token scope management (NEW!)
EXISTING STORIES:
✓ US004: Register OAuth client - Status: Done - KEEP
⚠ US005: Request access token - Status: Todo - UPDATE
Changes: Add AC5, Add RFC 7636 to Technical Notes, Add 2 Integration tests
Diff (AC): + AC5 "Given public client, When request with PKCE..."
Diff (Technical Notes): + RFC 7636 (PKCE)
✓ US006: Validate access token - Status: Backlog - KEEP
✓ US007: Refresh expired token - Status: In Progress - KEEP
✗ US008: Custom token formats - Status: Todo - OBSOLETE (feature removed)
+ US009: Token scope management - NEW (14h, 20 tests)
OPERATIONS: 3 keep, 1 update, 1 cancel, 1 create
WARNINGS:
- ⚠️ US005 (Todo): AC changed, Standards Research updated
- ⚠️ US008 (Todo): Feature removed - check dependencies
Type "confirm" to execute.
```
---
**Version:** 1.0.0
**Last Updated:** 2025-11-20

488
skills/ln-300-story-pipeline/SKILL.md Normal file
View File

@@ -0,0 +1,488 @@
---
name: ln-300-story-pipeline
description: Orchestrates complete Story workflow from task planning to Done. Delegates to ln-310-story-decomposer, ln-320-story-validator, ln-330-story-executor for full automation.
---
# Linear Story Processor (Orchestrator)
Orchestrate complete Story processing workflow from task planning through verification, execution, and review. This skill coordinates existing Story lifecycle using specialized workers.
## Overview
### What This Skill Does
Coordinates the complete processing pipeline for an existing Story:
- Auto-discovers Team ID from kanban_board.md
- Loads Story metadata ONLY (ID, title, status, labels - NO description)
- **Phase 1:** Discovery (Team ID + Story ID)
- **Phase 2:** Task Planning (delegates to ln-310-story-decomposer)
- **Phase 3:** Verification & Execution Loop (ln-320-story-validator prepares tasks, ln-330-story-executor executes them, explicit delegation to ln-340-story-quality-gate Pass 1 + Pass 2)
- **Phase 4:** Completion Report (Story Done automatically, full pipeline automation)
### When to Use This Skill
This skill should be used when:
- Process existing Story from planning to completion
- Automate full Story pipeline (tasks → verify → execute → review)
- Story already exists in Linear (e.g., US001, API-53)
- Need end-to-end orchestration without manual intervention
**Prerequisites:**
- Story exists in Linear
- Story has Acceptance Criteria defined
- Requirements are clear
### When NOT to Use
Do NOT use if:
- Story doesn't exist → Use ln-220-story-coordinator first to create Story
- Only need task planning → Use ln-310-story-decomposer directly
- Only need execution → Use ln-330-story-executor directly
- Story is vague (no AC) → Refine Story first
---
## Core Concepts
### Orchestrator Pattern
**ln-300-story-pipeline is a pure coordinator** - it does NOT execute work directly:
- ✅ Discovers context (Team ID, Story ID)
- ✅ Loads Story metadata ONLY (no full description)
- ✅ Makes routing decisions (which worker to invoke)
- ✅ Delegates all work via Skill tool
- ✅ Manages workflow state transitions
- ❌ Does NOT generate documents (workers do this)
- ❌ Does NOT create/update Linear issues (workers do this)
- ❌ Does NOT execute tasks (workers do this)
**Workers**:
- **ln-310-story-decomposer**: Plans and creates/replans tasks (1-6 implementation tasks)
- **ln-320-story-validator**: Verifies Story + Tasks against industry standards, auto-fixes, approves (Backlog → Todo)
- **ln-330-story-executor**: Executes all tasks through their workflow (Todo → In Progress → To Review → Done)
- **ln-340-story-quality-gate**: Reviews completed Story (Pass 1: manual testing + test task creation, Pass 2: final verification → Done)
### Workflow Pattern: Looping Orchestrator
**Pattern**: Orchestrator reloads metadata after each worker completes, then re-evaluates state.
**Flow**:
`
Phase 1: Discovery → Phase 2: Task Planning (ln-310-story-decomposer) →
Phase 3: Loop (Verify → Execute → Review Pass 1 + explicit Pass 2 delegation) →
[If new task created] → ln-320-story-validator revalidates Backlog tasks → ln-330-story-executor executes them →
[All tasks Done + test task Done] → explicit Pass 2 delegation → Story Done → Phase 4: Report
`
**Key Principle**: After each worker, reload Story + Tasks metadata (NOT full descriptions) and decide next step.
### Auto-Discovery
**Team ID**: Auto-discovered from `docs/tasks/kanban_board.md` Linear Configuration table (see CLAUDE.md "Configuration Auto-Discovery").
**Story ID**: Parsed from request: "for US001" or "for API-53" or "process US001"
---
## Workflow
### Phase 0: Checkpoint Setup
**Optional checkpoint:**
- If `docs/tasks/checkpoints/[story_id].md` exists → mark progress checkboxes as phases complete
- If file missing → continue without errors (checkpoint optional)
### Phase 1: Discovery (Automated)
Auto-discovers Team ID from `docs/tasks/kanban_board.md`.
Parses request for:
- **Story ID**: "for US001" or "process API-53"
**Validation**:
- Team ID exists in kanban_board.md
- Story ID format valid (e.g., US001, API-53)
Load Story metadata ONLY:
```
Story {
id: string,
title: string,
status: string (Backlog | Todo | In Progress | To Review | Done),
labels: string[]
}
```
**NO full description loaded** - token efficiency.
### Phase 2: Task Planning
**Check**: Does Story have tasks?
Query Linear: `list_issues(parentId=Story.id)`
**Decision**:
- **ALWAYS** delegate to ln-310-story-decomposer (Decompose-First Pattern)
- ln-310-story-decomposer will build IDEAL plan and choose CREATE (count=0) or REPLAN (count≥1) mode automatically
- Rationale: Stories with ≥3 tasks MUST be replanned if AC changed (current logic skips replan)
**Invocation**:
```
🔄 [PROCESSOR] Phase 2: Delegating task planning to ln-310-story-decomposer
Skill(skill: "ln-310-story-decomposer", context: {
storyId: Story.id,
teamId: teamId
})
```
**ln-310-story-decomposer will**:
- Analyze Story (AC, Technical Notes)
- Build IDEAL task plan (1-6 tasks, Foundation-First execution order)
- Create or replan tasks in Linear
- Update kanban_board.md
- Return: Task URLs + summary
**After completion**: Reload Story + Tasks metadata.
### Phase 3: Story Verification & Execution Loop
This phase loops until Story status = "To Review".
**Step 1: Story Verification**
**Trigger**: Story status = "Backlog" OR Tasks exist but not verified
Delegate to ln-320-story-validator:
```
🔄 [PROCESSOR] Phase 3 Step 1: Delegating verification to ln-320-story-validator
Skill(skill: "ln-320-story-validator", context: {
storyId: Story.id,
teamId: teamId
})
```
**ln-320-story-validator will**:
- Load Story + Tasks descriptions (sequential, one by one)
- Auto-fix all 16 verification criteria
- Auto-approve (Backlog → Todo)
- Update Story + Tasks status in Linear
- Return: Summary (changes, guides, warnings)
**After completion**: Reload Story + Tasks metadata.
**Step 2: Story Execution**
**Trigger**: Story status = "Todo" OR "In Progress"
Delegate to ln-330-story-executor:
```
🔄 [PROCESSOR] Phase 3 Step 2: Delegating execution to ln-330-story-executor
Skill(skill: "ln-330-story-executor", context: {
storyId: Story.id,
teamId: teamId
})
```
**ln-330-story-executor will**:
- Orchestrate task execution with strict priorities: Priority 0 = To Review (ln-332-task-reviewer), Priority 1 = To Rework (ln-333-task-rework), Priority 2 = Todo (ln-331-task-executor / ln-334-test-executor)
- Rely on ln-320-story-validator to move any fix/refactor/test tasks from Backlog to Todo before picking them up (new work always re-enters through ln-320-story-validator)
- Invoke ln-332-task-reviewer, ln-333-task-rework, ln-331-task-executor, ln-334-test-executor
- When all tasks Done → Explicitly delegate to ln-340-story-quality-gate Pass 1 (via Skill tool)
- When test task Done → Explicitly delegate to ln-340-story-quality-gate Pass 2 (via Skill tool) → Story Done
- Return: Execution summary
**After completion**: Reload Story + Tasks metadata.
**Step 3: Story Review Pass 1 + Pass 2 (Explicitly Delegated by ln-330-story-executor)**
**Trigger**: ln-330-story-executor explicitly delegates to ln-340-story-quality-gate Pass 1 when all implementation tasks Done
**ln-340-story-quality-gate Pass 1 will** (Early Exit Pattern):
- Phase 3: Code Quality Analysis (if fail → create refactoring task → ln-320-story-validator re-approves Backlog → Todo → Loop back to ln-330-story-executor)
- Phase 4: Regression Check (if fail → create fix task → ln-320-story-validator re-approves Backlog → Todo → Loop back to ln-330-story-executor)
- Phase 5: Manual Testing (if fail → create fix task → ln-320-story-validator re-approves Backlog → Todo → Loop back to ln-330-story-executor)
- Phase 6: Verdict
* **Path A**: All passed → Create test task (via ln-350-story-test-planner) → ln-320-story-validator revalidates Backlog → Todo → Loop back to ln-330-story-executor
* **Path B**: Issues found → ln-320-story-validator revalidates Backlog → Todo → Loop back to ln-330-story-executor
**ln-340-story-quality-gate Pass 2 explicit delegation**:
- **Trigger**: ln-330-story-executor detects test task Done → Updates Story status In Progress → To Review → Explicitly delegates Pass 2 (via Skill tool)
- **Pass 2 will**: Verify tests (E2E 2-5, Integration 3-8, Unit 5-15, Priority ≥15) → Story To Review → Done
**Loop Condition**: If new task created (fix/refactoring/test), Phase 3 restarts from ln-320-story-validator to approve Backlog → Todo before ln-330-story-executor executes again.
**Exit Condition**: Story status = "Done" (all tasks Done, test task Done, Pass 2 passed)
### Phase 4: Completion Report
**Trigger**: Story status = "Done" (all tasks Done, test task Done, Pass 2 passed automatically)
```
🔄 [PROCESSOR] Phase 4: Story processing complete
Story Status: Done
All Tasks: Done
Pipeline: Todo → In Progress → To Review → Done (fully automated)
Summary:
- Implementation tasks: Completed
- Code Quality → Regression → Manual Testing: Passed
- Test task: Completed (E2E 2-5, Integration 3-8, Unit 5-15, Priority ≥15)
- Pass 2: Verified and approved
Story successfully processed from planning to Done without manual intervention.
```
**Result**: Story fully automated from task planning to Done status.
---
## Critical Rules
### 1. Metadata-Only Loading
**HARD RULE**: Orchestrator loads ONLY Story + Tasks metadata (ID, title, status, labels).
**NO full descriptions loaded**:
- Prevents token waste
- Scales to Stories with many tasks
- Workers load full descriptions when needed
### 2. Strict Delegation
**Orchestrator responsibilities**:
- ✅ Discovery (Team ID, Story ID)
- ✅ Metadata loading (ID, title, status, labels)
- ✅ Routing decisions (which worker to invoke)
- ✅ Workflow state management
**Worker responsibilities** (NOT orchestrator):
- ❌ Generating documents → Workers
- ❌ Loading full descriptions → Workers
- ❌ Creating/updating Linear issues → Workers
- ❌ Executing tasks → Workers
- ❌ Running tests → Workers
### 3. Story Status Responsibility Matrix
**HARD RULE**: Only designated skills can update Story status. Clear ownership prevents conflicts.
| Story Status Transition | Responsible Skill | When |
|-------------------------|-------------------|------|
| **Backlog → Todo** | ln-320-story-validator | After auto-fix and approval (Phase 3 Step 1) |
| **Todo → In Progress** | ln-330-story-executor | First task execution starts (Phase 3 Step 2, Priority 2) |
| **In Progress → To Review** | ln-330-story-executor | All tasks Done (Phase 3 Step 2 → Phase 4 transition) |
| **To Review → Done** | ln-340-story-quality-gate Pass 2 | All tests verified, Priority ≥15 covered (Phase 4 Pass 2) |
**Why this matters**:
- Prevents duplicate updates from multiple skills
- Clear audit trail: each transition has ONE owner
- ln-300-story-pipeline orchestrates but does NOT update status directly
### 4. Loop After Each Worker
**Pattern**: After each worker completes, orchestrator:
1. Reloads Story + Tasks metadata
2. Re-evaluates state
3. Decides: next worker OR loop back OR complete
**Example**:
```
ln-330-story-executor completes → Reload metadata → Check Story status
- Story status = "In Progress" → Loop back to ln-330-story-executor
- Story status = "To Review" → Phase 4 (report completion)
```
### 4. Full Pipeline Automation
**Automation Principle**: Orchestrator runs entire pipeline without user prompts (full automation from task planning to Story Done).
**Workers handle prompts**:
- ln-310-story-decomposer: Shows preview, waits for "confirm"
- ln-320-story-validator: Shows summary, auto-approves
- ln-330-story-executor: Orchestrates without prompts (workers may prompt), auto-invokes Pass 1 + Pass 2
**Full Automation**: No manual intervention required. Story lifecycle fully automated: Todo → In Progress → To Review → Done.
---
## Definition of Done
Before completing work, verify ALL checkpoints:
**✅ Checkpoint Setup (Phase 0):**
- [ ] Checkpoint file created/loaded: `docs/tasks/checkpoints/[story_id].md`
- [ ] Resume point identified (if checkpoint existed)
**✅ Team ID Discovered (Phase 1):**
- [ ] Team ID loaded from kanban_board.md OR requested from user
- [ ] Story ID parsed from request
- [ ] Story metadata loaded (ID, title, status, labels - NO description)
**✅ Task Planning Completed (Phase 2):**
- [ ] Checked if tasks exist (count ≥ 0)
- [ ] Delegated to ln-310-story-decomposer to build the IDEAL plan and choose CREATE or REPLAN mode
- [ ] Reloaded metadata after ln-310-story-decomposer completed
**✅ Verification & Execution Loop (Phase 3):**
- [ ] Delegated to ln-320-story-validator (Story Backlog → Todo)
- [ ] Delegated to ln-330-story-executor (orchestrates task execution with To Review → To Rework → Todo priorities)
- [ ] New fix/refactor/test tasks routed back through ln-320-story-validator before execution
- [ ] ln-330-story-executor auto-invoked ln-340-story-quality-gate Pass 1 (Code Quality → Regression → Manual Testing)
- [ ] Pass 1 created test task (ln-320-story-validator re-approved it before execution)
- [ ] ln-330-story-executor executed test task
- [ ] ln-330-story-executor auto-invoked ln-340-story-quality-gate Pass 2 after test task Done
- [ ] Pass 2 verified tests (E2E 2-5, Integration 3-8, Unit 5-15, Priority ≥15)
- [ ] Pass 2 updated Story status: To Review → Done
- [ ] Loop completed: Story status = "Done"
**✅ Completion Report (Phase 4):**
- [ ] Story status = "Done"
- [ ] All tasks Done
- [ ] Full pipeline automation confirmed: Todo → In Progress → To Review → Done
- [ ] Reported to user: "Story successfully processed from planning to Done without manual intervention"
- [ ] Checkpoint file deleted: `docs/tasks/checkpoints/[story_id].md`
**Output**: Story fully automated from task planning to Done status (no manual intervention).
---
## Integration with Ecosystem
### Called By
Users directly: "Process US001" or "Run full pipeline for API-53"
### Calls (via Skill tool)
- **ln-310-story-decomposer**: Task planning (Phase 2)
- **ln-320-story-validator**: Story verification (Phase 3 Step 1)
- **ln-330-story-executor**: Story execution (Phase 3 Step 2)
- ln-330-story-executor auto-invokes ln-340-story-quality-gate Pass 1 (Phase 3 Step 3)
### Next Steps
After ln-300-story-pipeline completes:
- **Story Done**: No further action required. Story fully automated from task planning to Done status.
- **Full Pipeline Automation**: Todo → In Progress → To Review → Done (no manual intervention)
---
## Best Practices
### Orchestrator Responsibilities
**DO**:
- ✅ Load Story + Tasks metadata ONLY
- ✅ Make routing decisions
- ✅ Delegate to workers
- ✅ Reload metadata after each worker
- ✅ Manage loop logic
**DON'T**:
- ❌ Load full descriptions (workers do this)
- ❌ Generate documents (workers do this)
- ❌ Create/update Linear issues (workers do this)
- ❌ Execute tasks (workers do this)
- ❌ Prompt user mid-pipeline (workers do this)
### Worker Communication
**Context Propagation**: Pass minimal context to workers (Team ID, Story ID only). Workers discover full data themselves.
**Trust Worker Results**: Workers return summary, orchestrator doesn't re-verify.
**Error Handling**: If worker returns error, report to user and stop pipeline.
### Loop Management
**Reload After Worker**: Always reload Story + Tasks metadata after worker completes.
**Exit Condition**: Loop exits when Story status = "To Review" AND all tasks Done.
**Infinite Loop Protection**: Max 10 iterations per loop (safety net). If exceeded, report to user.
---
## Quick Examples
### Example 1: New Story (No Tasks)
**Request**: "Process US001: Implement OAuth token authentication"
**Execution**:
- Phase 1: Team ID discovered, Story ID = US001, Status = Backlog
- Phase 2: No tasks → Invoke ln-310-story-decomposer
- ln-310-story-decomposer: Analyze Story (5 AC), create 3 tasks (Token generation 4h, Validation middleware 3h, Refresh logic 5h)
- Reload metadata: Story has 3 tasks
- Phase 3 Step 1: Invoke ln-320-story-validator
- ln-320-story-validator: Auto-fix + approve (Backlog → Todo)
- Reload metadata: Story status = Todo
- Phase 3 Step 2: Invoke ln-330-story-executor
- ln-330-story-executor: Execute 3 tasks (Priority 2: Todo)
- ln-330-story-executor: Auto-invoke ln-340-story-quality-gate Pass 1
- Pass 1: Code Quality → Regression → Manual Testing → All passed → Create test task
- ln-320-story-validator re-approved test task (Backlog → Todo)
- Reload metadata: Story has 4 tasks (1 test task in Todo)
- Phase 3 Step 2 (Loop): ln-330-story-executor continues
- ln-330-story-executor: Execute test task (Priority 2)
- Test task Done
- ln-330-story-executor: Update Story In Progress → To Review
- ln-330-story-executor: Auto-invoke ln-340-story-quality-gate Pass 2
- Pass 2: Verify tests (E2E 2-5, Integration 3-8, Unit 5-15, Priority ≥15) → Pass
- Pass 2: Update Story To Review → Done
- Reload metadata: Story status = Done, all tasks Done
- Phase 4: Report "Story successfully processed from planning to Done without manual intervention"
**Result**: Story fully automated from Backlog to Done (no manual intervention).
### Example 2: Existing Story (Tasks Already Exist)
**Request**: "Process US005" (Story already has 4 tasks)
**Execution**:
- Phase 1: Team ID discovered, Story ID = US005, Status = Todo
- Phase 2: 4 tasks exist (count ≥ 3) → Skip task planning
- Phase 3 Step 1: Invoke ln-320-story-validator
- ln-320-story-validator: Auto-fix + approve (already Todo, validate tasks)
- Reload metadata: Story status = Todo
- Phase 3 Step 2: Invoke ln-330-story-executor
- ln-330-story-executor: Execute 4 tasks (Priority 2: Todo)
- ln-330-story-executor: Auto-invoke ln-340-story-quality-gate Pass 1
- Pass 1: Code Quality → Regression → Manual Testing → All passed → Create test task
- ln-330-story-executor Priority 0: Auto-verify test task (Backlog → Todo)
- Reload metadata: Story has 5 tasks (1 test task in Todo)
- Phase 3 Step 2 (Loop): ln-330-story-executor continues
- ln-330-story-executor: Execute test task (Priority 2)
- Test task Done
- ln-330-story-executor: Update Story In Progress → To Review
- ln-330-story-executor: Auto-invoke ln-340-story-quality-gate Pass 2
- Pass 2: Verify tests (E2E 2-5, Integration 3-8, Unit 5-15, Priority ≥15) → Pass
- Pass 2: Update Story To Review → Done
- Reload metadata: Story status = Done, all tasks Done
- Phase 4: Report "Story successfully processed from planning to Done without manual intervention"
**Result**: Story fully automated from Todo to Done (no manual intervention).
---
## Reference Files
**Checkpoint Format:**
- `references/checkpoint_format.md` - Execution checkpoint file structure for context recovery
---
## Chat Output Prefix
Use emoji prefix for visual differentiation:
- 🔄 [PROCESSOR] - ln-300-story-pipeline (orchestrator)
**Purpose**: Helps users track orchestrator progress when multiple workers are invoked.
---
**Version:** 2.1.0 (Fixed Writing Style: "Use this skill when" → "This skill should be used when" for skill-creator compliance.)
**Last Updated:** 2025-11-16

133
skills/ln-300-story-pipeline/diagram.html Normal file
View File

@@ -0,0 +1,133 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>ln-300-story-pipeline Workflow Diagram</title>
<link rel="stylesheet" href="../shared/css/diagram.css">
<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
<script>
mermaid.initialize({
startOnLoad: true,
theme: 'base',
themeVariables: {
primaryColor: '#2E7D32',
primaryTextColor: '#fff',
primaryBorderColor: '#1B5E20',
lineColor: '#666',
secondaryColor: '#00695C',
tertiaryColor: '#0288D1',
background: '#fff',
mainBkg: '#E8F5E9',
secondBkg: '#B2DFDB',
tertiaryBkg: '#B3E5FC',
loopTextColor: '#fff'
}
});
</script>
</head>
<body>
<div class="container">
<h1>ln-300-story-pipeline Workflow Diagram</h1>
<p class="subtitle">Story Processing Orchestrator - Looping Workflow Pattern</p>
<div class="legend">
<h3>Color Coding:</h3>
<ul>
<li><span class="legend-box discovery"></span> Discovery (Team ID, Story ID)</li>
<li><span class="legend-box planning"></span> Task Planning (ln-310-story-decomposer)</li>
<li><span class="legend-box verification"></span> Verification (ln-320-story-validator)</li>
<li><span class="legend-box execution"></span> Execution (ln-330-story-executor)</li>
<li><span class="legend-box review"></span> Review Pass 1 (ln-340-story-quality-gate)</li>
<li><span class="legend-box decision"></span> Decision Points</li>
<li><span class="legend-box completion"></span> Completion (Report)</li>
</ul>
</div>
<div class="mermaid">
graph TD
Start([User Request: Process US001]) --> Phase1[Phase 1: Discovery<br/>Load Team ID + Story metadata<br/>ID, title, status, labels ONLY]
Phase1 --> Phase2Decision{Phase 2: Task Planning<br/>Has tasks?<br/>count >= 3?}
Phase2Decision -->|No or < 3| Phase2[Phase 2: Task Planning<br/>ln-310-story-decomposer<br/>Create/Replan 1-6 tasks]
Phase2Decision -->|Yes >= 3| Phase3Step1
Phase2 --> Reload1[Reload Story + Tasks metadata]
Reload1 --> Phase3Step1
Phase3Step1[Phase 3 Step 1: Verification<br/>ln-320-story-validator<br/>Auto-fix + Approve Backlog → Todo]
Phase3Step1 --> Reload2[Reload Story + Tasks metadata]
Reload2 --> Phase3Step2[Phase 3 Step 2: Execution<br/>ln-330-story-executor<br/>Priority 0: Backlog auto-verify<br/>Priority 1-3: Execute tasks]
Phase3Step2 --> AutoInvoke[Auto-invoke<br/>ln-340-story-quality-gate Pass 1<br/>Early Exit Pattern]
AutoInvoke --> Pass1Decision{Pass 1 Verdict?}
Pass1Decision -->|All passed| CreateTestTask[Create test task<br/>via ln-350-story-test-planner<br/>Backlog status]
Pass1Decision -->|Code quality issues| CreateRefactorTask[Create refactoring task<br/>Backlog status]
Pass1Decision -->|Regression/testing failed| CreateFixTask[Create fix task<br/>Backlog status]
CreateTestTask --> AutoVerifyTest[Priority 0: Auto-verify<br/>via ln-320-story-validator<br/>Backlog → Todo]
CreateRefactorTask --> AutoVerifyRefactor[Priority 0: Auto-verify<br/>via ln-320-story-validator<br/>Backlog → Todo]
CreateFixTask --> AutoVerifyFix[Priority 0: Auto-verify<br/>via ln-320-story-validator<br/>Backlog → Todo]
AutoVerifyTest --> Reload3[Reload Story + Tasks metadata]
AutoVerifyRefactor --> Reload3
AutoVerifyFix --> Reload3
Reload3 --> LoopCheck{Story status?<br/>All tasks Done?}
LoopCheck -->|In Progress OR<br/>Tasks pending| Phase3Step2
LoopCheck -->|Test task Done| AutoInvokePass2[ln-330-story-executor:<br/>Update Story In Progress → To Review<br/>Auto-invoke Pass 2]
AutoInvokePass2 --> Pass2[ln-340-story-quality-gate Pass 2<br/>Verify tests: E2E 2-5<br/>Integration 3-8, Unit 5-15<br/>Priority ≥15]
Pass2 --> Pass2Decision{Pass 2 Verdict?}
Pass2Decision -->|Pass| StoryDone[Story To Review → Done<br/>Full automation complete]
Pass2Decision -->|Fail| CreatePass2Fix[Create fix tasks<br/>Backlog → Auto-verify → Loop]
StoryDone --> Phase4[Phase 4: Completion Report<br/>Story Done<br/>Full pipeline automation:<br/>Todo → In Progress → To Review → Done]
CreatePass2Fix --> Reload3
Phase4 --> End([Story Done])
classDef discoveryClass fill:#E8F5E9,stroke:#1B5E20,stroke-width:2px
classDef planningClass fill:#FFF3E0,stroke:#E65100,stroke-width:2px
classDef verificationClass fill:#E3F2FD,stroke:#0277BD,stroke-width:2px
classDef executionClass fill:#FCE4EC,stroke:#C2185B,stroke-width:2px
classDef reviewClass fill:#F3E5F5,stroke:#6A1B9A,stroke-width:2px
classDef decisionClass fill:#FFF9C4,stroke:#F57F17,stroke-width:2px
classDef completionClass fill:#C8E6C9,stroke:#2E7D32,stroke-width:3px
classDef reloadClass fill:#E0E0E0,stroke:#424242,stroke-width:1px
class Start,Phase1 discoveryClass
class Phase2Decision,Phase2 planningClass
class Phase3Step1,AutoVerifyTest,AutoVerifyRefactor,AutoVerifyFix verificationClass
class Phase3Step2,AutoInvoke,AutoInvokePass2 executionClass
class Pass1Decision,Pass2Decision,LoopCheck decisionClass
class CreateTestTask,CreateRefactorTask,CreateFixTask,CreatePass2Fix,Pass2 reviewClass
class Reload1,Reload2,Reload3 reloadClass
class StoryDone,Phase4,End completionClass
</div>
<div class="notes">
<h3>Workflow Notes:</h3>
<ul>
<li><strong>Phase 1:</strong> Discovery - Auto-discover Team ID from kanban_board.md, parse Story ID from request</li>
<li><strong>Phase 2:</strong> Task Planning - Delegate to ln-310-story-decomposer if tasks don't exist or count < 3</li>
<li><strong>Phase 3 Step 1:</strong> Verification - ln-320-story-validator auto-fixes + approves Story (Backlog → Todo)</li>
<li><strong>Phase 3 Step 2:</strong> Execution - ln-330-story-executor orchestrates with Priority 0 (Backlog auto-verify) → Priority 1-3 (task execution)</li>
<li><strong>Pass 1 (Early Exit):</strong> Code Quality → Regression → Manual Testing. Creates test/refactor/fix task in Backlog</li>
<li><strong>Priority 0 Auto-Verify:</strong> All new tasks (test/refactor/fix) auto-verified via ln-320-story-validator (Backlog → Todo) before execution</li>
<li><strong>Pass 2 Auto-Invocation:</strong> When test task Done, ln-330-story-executor updates Story (In Progress → To Review) and auto-invokes Pass 2</li>
<li><strong>Loop:</strong> After each worker, reload Story + Tasks metadata. Loop continues while tasks pending or Pass 2 creates fixes</li>
<li><strong>Exit Condition:</strong> Story status = "Done" (all tasks Done, test task Done, Pass 2 passed)</li>
<li><strong>Phase 4:</strong> Completion Report - Story Done, full pipeline automation (Todo → In Progress → To Review → Done)</li>
</ul>
</div>
<div class="footer">
<p><strong>Pattern:</strong> Looping Workflow (Pattern 4) with Full Automation</p>
<p><strong>Type:</strong> Orchestrator - delegates all work via Skill tool</p>
<p><strong>Key Principle:</strong> Metadata-only loading, strict delegation, Priority 0 auto-verify, auto Pass 2, full pipeline automation (Todo → Done)</p>
<p><strong>Version:</strong> 1.1.1 | <strong>Last Updated:</strong> 2025-11-15</p>
</div>
</div>
</body>
</html>

13
skills/ln-300-story-pipeline/references/checkpoint_format.md Normal file
View File

@@ -0,0 +1,13 @@
# Checkpoint: [Story ID]
## Progress
- [ ] Phase 1: Discovery
- [ ] Phase 2: Task Planning (ln-310)
- [ ] Phase 3 Step 1: Verification (ln-320)
- [ ] Phase 3 Step 2: Execution (ln-330)
- [ ] Phase 3 Step 3: Quality Pass 1 (ln-340)
- [ ] Phase 3 Step 3: Quality Pass 2 (ln-340)
- [ ] Phase 4: Completion
**Current Step:** Phase 1
**Story Status:** Backlog

61
skills/ln-310-story-decomposer/SKILL.md Normal file
View File

@@ -0,0 +1,61 @@
---
name: ln-310-story-decomposer
description: Orchestrates task operations. Analyzes Story, builds optimal plan (1-6 tasks), delegates to ln-311-task-creator (CREATE/ADD) or ln-312-task-replanner (REPLAN). Auto-discovers team ID.
---
# Linear Task Planner (Orchestrator)
Coordinates creation or replanning of implementation tasks for a Story. Builds the ideal plan first, then routes to workers.
## Purpose & Scope
- Auto-discover Team ID, load Story context (AC, Technical Notes, Context)
- Build optimal implementation task plan (1-6 tasks) in Foundation-First order
- Detect mode and delegate: CREATE/ADD -> ln-311-task-creator, REPLAN -> ln-312-task-replanner
- Strip any Non-Functional Requirements; only functional scope becomes tasks
- Never creates/updates Linear or kanban directly (workers do)
## When to Use
- Need tasks for a Story with clear AC/Technical Notes
- Story requirements changed and existing tasks must be updated
- Not for tests (ln-350-story-test-planner handles test tasks)
## Workflow (concise)
- **Phase 1 Discovery:** Auto-discover Team ID (docs/tasks/kanban_board.md); parse Story ID from request.
- **Phase 2 Decompose (always):** Load Story (AC, Technical Notes, Context), assess complexity, build IDEAL plan (1-6 tasks), apply Foundation-First execution order, extract guide links.
- **Phase 3 Check & Detect Mode:** Query Linear for existing tasks (metadata only). Detect mode by count + user keywords (add/replan).
- **Phase 4 Delegate:** Call the right worker with Story data, IDEAL plan/append request, guide links, existing task IDs if any; autoApprove=true.
- **Phase 5 Verify:** Ensure worker returns URLs/summary and updated kanban_board.md; report result.
## Mode Matrix
| Condition | Mode | Delegate | Payload |
|-----------|------|----------|---------|
| Count = 0 | CREATE | ln-311-task-creator | taskType=implementation, Story data, IDEAL plan, guideLinks |
| Count > 0 AND "add"/"append" | ADD | ln-311-task-creator | taskType=implementation, appendMode=true, newTaskDescription, guideLinks |
| Count > 0 AND replan keywords | REPLAN | ln-312-task-replanner | taskType=implementation, Story data, IDEAL plan, guideLinks, existingTaskIds |
| Count > 0 AND ambiguous | ASK | Clarify with user | — |
## Critical Rules
- Decompose-first: always build IDEAL plan before looking at existing tasks.
- Foundation-First execution order: DB -> Repository -> Service -> API -> Frontend.
- Task limits: 1-6 tasks, 3-5h each; cap total at 6 tasks.
- Linear creation must be sequential: create one task, confirm success, then create the next (no bulk) to catch errors early.
- No test creation anywhere in implementation tasks.
- No code snippets in descriptions; workers own task documents and Linear/kanban updates.
- Language preservation: keep Story language (EN/RU) in any generated content by workers.
## Definition of Done (orchestrator)
- Team ID discovered; Story ID parsed.
- Story loaded; IDEAL plan built (1-6 tasks) with Foundation-First order and guide links.
- Existing tasks counted; mode selected (CREATE/ADD/REPLAN or ask).
- Worker invoked with correct payload and autoApprove=true.
- Worker summary received (Linear URLs/operations) and kanban update confirmed.
- Next steps returned (ln-320-story-validator then ln-330-story-executor).
## Reference Files
- Templates owned by ln-311-task-creator: `../ln-311-task-creator/references/task_template_implementation.md`
- Replan algorithm details: `../ln-312-task-replanner/references/replan_algorithm.md`
- Auto-discovery notes: `CLAUDE.md`, `docs/tasks/kanban_board.md`
---
Version: 8.0.0 (Condensed orchestrator flow and mode matrix)
Last Updated: 2025-11-26

79
skills/ln-310-story-decomposer/diagram.html Normal file
View File

@@ -0,0 +1,79 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>x-task-manager - State Diagram</title>
<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
<link rel="stylesheet" href="../shared/css/diagram.css">
</head>
<body>
<div class="container">
<header>
<h1>🔧 x-task-manager</h1>
<p class="subtitle">Task Manager - Orchestrator v6.1.0</p>
</header>
<div class="info-box">
<h3>📋 Overview</h3>
<ul>
<li><strong>Purpose:</strong> Orchestrator for task operations (create/replan) with automatic decomposition</li>
<li><strong>Pattern:</strong> Orchestrator v6.1.0 - Delegates to workers (ln-311-task-creator, ln-312-task-replanner) via Skill tool</li>
<li><strong>Decompose-First:</strong> Build IDEAL plan ALWAYS (1-6 tasks), then check existing and delegate to workers</li>
<li><strong>Modes:</strong> CREATE (no tasks → ln-311-task-creator) or REPLAN (has tasks → ln-312-task-replanner)</li>
<li><strong>Ordering:</strong> Foundation-First execution order (Database → Repository → Service → API)</li>
<li><strong>Next Step:</strong> ln-320-story-validator ONLY (обязательная верификация перед выполнением)</li>
</ul>
</div>
<div class="diagram-container">
<div class="mermaid">
%% x-task-manager: Task Manager (Orchestrator v6.1.0)
%% Universal task operations (create/replan) with automatic decomposition
%% Decompose-First Pattern: Build IDEAL plan → Check existing → Delegate to workers
graph TD
Start([Start: x-task-manager<br/>ORCHESTRATOR]) --> Phase1[Phase 1: Discovery<br/>Auto-discover Team ID<br/>Parse Story ID from request]
Phase1 --> Phase2[Phase 2: Analyze & Decompose ALWAYS<br/>Load Story from Linear<br/>Build IDEAL task plan 1-6<br/>Extract guide links<br/>Foundation-First ordering]
Phase2 --> Phase3{Phase 3: Check<br/>Existing Tasks?<br/>Query Linear}
Phase3 -->|Count = 0| CreateMode[CREATE MODE<br/>No existing tasks]
Phase3 -->|Count ≥ 1| ReplanMode[REPLAN MODE<br/>Has existing tasks]
CreateMode --> Phase4a[Phase 4a: Delegate to ln-311-task-creator<br/>Skill tool with:<br/>taskType: "implementation"<br/>+ IDEAL plan + guide links]
Phase4a --> WorkerCreate[ln-311-task-creator WORKER:<br/>• Generate 7-section docs<br/>• Validate NO tests<br/>• Show preview<br/>• User confirms<br/>• Create in Linear<br/>• Update kanban_board.md]
WorkerCreate --> Phase5[Phase 5: Post-Execution<br/>Receive Summary from worker<br/>Return to user]
ReplanMode --> Phase4b[Phase 4b: Delegate to ln-312-task-replanner<br/>Skill tool with:<br/>taskType: "implementation"<br/>+ IDEAL plan + existing IDs]
Phase4b --> WorkerReplan[ln-312-task-replanner WORKER:<br/>• Load existing tasks<br/>• Compare IDEAL vs existing<br/>• Show operations + diffs<br/>• User confirms<br/>• Execute operations<br/>• Update kanban_board.md]
WorkerReplan --> Phase5
Phase5 --> End([End: Return to user<br/>Summary + Linear URLs<br/><br/>Next Step ONLY:<br/>→ ln-320-story-validator])
%% Styling
classDef orchestrator fill:#e1f5fe,stroke:#0277bd,stroke-width:3px
classDef discovery fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
classDef processing fill:#fff9c4,stroke:#f57c00,stroke-width:2px
classDef decision fill:#ffe0b2,stroke:#e64a19,stroke-width:2px
classDef delegation fill:#e1bee7,stroke:#7b1fa2,stroke-width:2px
classDef worker fill:#c8e6c9,stroke:#388e3c,stroke-width:2px
classDef success fill:#a5d6a7,stroke:#2e7d32,stroke-width:2px
class Start orchestrator
class Phase1 discovery
class Phase2,CreateMode,ReplanMode processing
class Phase3 decision
class Phase4a,Phase4b delegation
class WorkerCreate,WorkerReplan worker
class Phase5Create,Phase5Replan,End success
</div>
</div>
<footer>
<p>x-task-manager v6.1.0 | Orchestrator Pattern | Mermaid.js</p>
</footer>
</div>
<script>
mermaid.initialize({ startOnLoad: true, theme: 'default', flowchart: { useMaxWidth: true, htmlLabels: true, curve: 'basis' } });
</script>
</body>
</html>

69
skills/ln-311-task-creator/SKILL.md Normal file
View File

@@ -0,0 +1,69 @@
---
name: ln-311-task-creator
description: Creates ALL task types (implementation, refactoring, test). Generates task documents from templates, validates type rules, creates in Linear, updates kanban. Invoked by orchestrators.
---
# Universal Task Creator
Worker that generates task documents and creates Linear issues for implementation, refactoring, or test tasks as instructed by orchestrators.
## Purpose & Scope
- Owns all task templates and creation logic (Linear + kanban updates)
- Generates full task documents per type (implementation/refactoring/test)
- Enforces type-specific hard rules (no new tests in impl, regression strategy for refactoring, risk matrix and limits for test)
- Drops NFR bullets if supplied; only functional scope becomes tasks
- Never decides scope itself; uses orchestrator input (plans/results)
## Invocation (who/when)
- **ln-310-story-decomposer:** CREATE (no tasks) or ADD (appendMode) for implementation tasks.
- **ln-340-story-quality-gate:** Create refactoring task when issues found.
- **ln-350-story-test-planner:** Create final test task after manual testing.
- Never called directly by users.
## Inputs
- Common: `taskType`, teamId, Story data (id/title/description with AC, Technical Notes, Context).
- Implementation CREATE: idealPlan (1-6 tasks), guideLinks.
- Implementation ADD: appendMode=true, newTaskDescription, guideLinks.
- Refactoring: codeQualityIssues, refactoringPlan, affectedComponents.
- Test: manualTestResults, testPlan (E2E 2-5, Integration 0-8, Unit 0-15, Priority ≤15), infra/doc/cleanup items.
## Workflow (concise)
1) **Context check:** For implementation (or ADD) review existing code/db/deps/docs to avoid duplicating components or columns; reuse instead of recreate.
2) **Template select:** Read template from `references/` based on taskType.
3) **Generate docs:** Fill sections for each task in plan/request using provided data and guide links.
4) **Validate type rules:** Stop with error if violation (see table below).
5) **Preview:** Show titles/goals/estimates/AC/components and totals.
6) **Confirmation required:** Proceed only after explicit confirm.
7) **Create issues:** Call Linear create_issue with parentId=Story, state=Backlog; capture URLs.
8) **Update kanban:** Add under Story in Backlog with correct Epic/indent.
9) **Return summary:** URLs, counts, hours, guide link count; next steps (validator/executor).
## Type Rules (must pass)
| taskType | Hard rule | What to verify |
|----------|-----------|----------------|
| implementation | No new test creation | Scan text for "write/create/add tests" etc.; allow only updating existing tests |
| refactoring | Regression strategy required | Issues listed with severity; plan in 3 phases; regression strategy (Baseline/Verify/Failure); preserve functionality |
| test | Risk-based plan required | Priority ≤15 scenarios; E2E 2-5, Integration 0-8, Unit 0-15, Total 10-28; no framework/library/DB tests |
## Critical Notes
- Foundation-First order for implementation is preserved from orchestrator; do not reorder.
- No code snippets; keep to approach, APIs, and pseudocode only.
- Documentation updates must be included in Affected Components/Docs sections.
- Language preservation: keep Story language (EN/RU) in generated tasks.
## Definition of Done
- Context check complete (existing components/schema/deps/docs reviewed; conflicts flagged).
- Documents generated with correct template and full sections.
- Type validation passed (no test creation for impl; regression strategy for refactor; risk matrix/limits for test).
- Preview shown and user confirmed.
- Linear issues created with parentId and URLs captured; state=Backlog.
- kanban_board.md updated under correct Epic/Story with indentation.
- Summary returned with URLs, totals, and next steps.
## Reference Files
- Templates (owned here): `references/task_template_implementation.md`, `references/refactoring_task_template.md`, `references/test_task_template.md`
- Kanban format: `docs/tasks/kanban_board.md`
---
Version: 5.0.0 (Condensed workflow, tabled type rules)
Last Updated: 2025-11-26

94
skills/ln-311-task-creator/diagram.html Normal file
View File

@@ -0,0 +1,94 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>ln-311-task-creator - Universal Factory</title>
<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
<link rel="stylesheet" href="../shared/css/diagram.css">
</head>
<body>
<div class="container">
<header>
<h1>ln-311-task-creator</h1>
<p class="subtitle">Universal Factory - Worker v1.0.0</p>
</header>
<div class="info-box">
<h2>Overview</h2>
<ul>
<li><strong>Purpose:</strong> Universal factory worker for creating ALL 3 task types (implementation, refactoring, test)</li>
<li><strong>Pattern:</strong> Worker v1.0.0 - Invoked by orchestrator (x-task-manager) via Skill tool with taskType parameter</li>
<li><strong>Templates:</strong>
<ul>
<li><code>implementation</code> → task_template_implementation.md (7 sections)</li>
<li><code>refactoring</code> → refactoring_task_template.md (7 sections)</li>
<li><code>test</code> → test_task_template.md (11 sections)</li>
</ul>
</li>
<li><strong>Type-Specific Validation:</strong>
<ul>
<li><code>implementation</code>: NO tests (tests in final Story task)</li>
<li><code>refactoring</code>: Regression Strategy required</li>
<li><code>test</code>: Priority ≥15 scenarios + Limits (2-5 E2E, 3-8 Integration, 5-15 Unit)</li>
</ul>
</li>
<li><strong>Input:</strong> IDEAL plan + guide links from orchestrator</li>
<li><strong>Output:</strong> Task URLs + summary → return to orchestrator</li>
</ul>
</div>
<div class="diagram-container">
<div class="mermaid">
graph TD
Start([Invoked by orchestrator<br/>taskType parameter]) --> SelectTemplate{Select Template<br/>by taskType}
SelectTemplate -->|implementation| T1[task_template_implementation.md<br/>7 sections]
SelectTemplate -->|refactoring| T2[refactoring_task_template.md<br/>7 sections]
SelectTemplate -->|test| T3[test_task_template.md<br/>11 sections]
T1 --> Phase1
T2 --> Phase1
T3 --> Phase1
Phase1[Phase 1: Generate Task Documents<br/>From IDEAL plan<br/>Fill template sections]
Phase1 --> Phase2{Phase 2: Type-Specific Validation<br/>implementation: NO tests<br/>refactoring: Regression Strategy<br/>test: Priority ≥15 + Limits}
Phase2 -->|Validation failed| Error([ERROR: Stop execution<br/>Report to orchestrator])
Phase2 -->|Validation passed| Phase3[Phase 3: Show Preview<br/>Task summaries<br/>Total count & hours]
Phase3 --> Phase4{Phase 4: User Confirmation}
Phase4 -->|"confirm"| Phase5[Phase 5: Create in Linear<br/>+ Update kanban_board.md]
Phase4 -->|Other input| Abort([Abort: Return to orchestrator])
Phase5 --> Success([SUCCESS<br/>Return task URLs + summary])
style Start fill:#e1f5fe
style Success fill:#c8e6c9
style Error fill:#ffcdd2
style Abort fill:#fff9c4
style SelectTemplate fill:#e1bee7
style T1 fill:#c8e6c9
style T2 fill:#fff3e0
style T3 fill:#ffcdd2
style Phase2 fill:#fff3e0
style Phase4 fill:#fff3e0
</div>
</div>
<footer>
<p>ln-311-task-creator v1.0.0 | Universal Factory Pattern | Mermaid.js</p>
</footer>
</div>
<script>
mermaid.initialize({
startOnLoad: true,
theme: 'default',
flowchart: {
useMaxWidth: true,
htmlLabels: true,
curve: 'basis'
}
});
</script>
</body>
</html>

515
skills/ln-311-task-creator/references/refactoring_task_template.md Normal file
View File

@@ -0,0 +1,515 @@
# Task Title: Refactor [Component/Feature Name]
**Epic:** [Epic N - Epic Name](link) *(optional)*
**User Story:** [USXXX Story Name](link) *(parent task - this task will have parentId=USXXX)*
**Related:** TEAM-XX, TEAM-YY
---
## Context
**Story:** [Story ID] [Story Title]
**Problems Found During Code Review:**
Review conducted in ln-340-story-quality-gate Pass 1 identified the following code quality issues requiring refactoring.
**Current State:**
- Code has quality issues (DRY/KISS/YAGNI/Architecture violations)
- Functionality works but maintainability/readability/performance affected
- Technical debt accumulating
**Desired State:**
- Same functionality preserved (HARD RULE: no behavior changes)
- Code quality improved (DRY/KISS/YAGNI principles applied)
- Architecture clean (proper layer boundaries)
- All existing tests pass (regression verification)
---
## Code Quality Issues
### Issue 1: [Category] - [Short Description]
**Category:** [DRY Violation / KISS Violation / YAGNI Violation / Architecture Issue / Guide Violation]
**Severity:** [HIGH / MEDIUM / LOW]
**Files Affected:**
- `path/to/file1.py:45-60` - [Brief description of issue location]
- `path/to/file2.py:120-135` - [Brief description of issue location]
**Problem:**
[Detailed description of what's wrong with current implementation]
**Before (Current Code):**
```language
// Example of problematic code
// Show actual code from codebase
```
**After (Proposed Fix):**
```language
// Example of refactored code
// Show how it should look after refactoring
```
**Benefits:**
- [Benefit 1: e.g., "DRY: 45 lines → 21 lines (53% reduction)"]
- [Benefit 2: e.g., "Maintainability: Fix bugs once, not 3 times"]
- [Benefit 3: e.g., "Testability: Unit test validator separately"]
**Why This Violates [Principle]:**
[Explain which principle violated and why it matters]
### Issue 2: [Category] - [Short Description]
**Category:** [DRY / KISS / YAGNI / Architecture / Guide Violation]
**Severity:** [HIGH / MEDIUM / LOW]
**Files Affected:**
- [List files and line numbers]
**Problem:**
[Description]
**Before:**
```language
[Current problematic code]
```
**After (Proposed):**
```language
[Refactored code]
```
**Benefits:**
- [Benefits list]
### Issue 3: [Category] - [Short Description]
**Category:** [DRY / KISS / YAGNI / Architecture / Guide Violation]
**Severity:** [HIGH / MEDIUM / LOW]
**Files Affected:**
- [List files]
**Problem:**
[Description]
**Verification (for YAGNI violations):**
```bash
# Command to verify code is unused
rg "function_name" --type language
# Output: No matches found (confirms dead code)
```
**Action:** [Delete / Simplify / Consolidate]
**Benefits:**
- [Benefits]
---
## Refactoring Goal
**Primary Goal:**
Resolve all identified code quality issues while preserving 100% of existing functionality.
**Specific Objectives:**
- [ ] Fix all DRY violations (eliminate code duplication)
- [ ] Fix all KISS violations (simplify over-engineered solutions)
- [ ] Fix all YAGNI violations (remove unused/premature features)
- [ ] Fix all architecture issues (restore proper layer boundaries)
- [ ] Fix all guide violations (align with project patterns)
**Success Criteria:**
- All issues from Code Quality Issues section resolved
- All existing tests pass (regression verification)
- Functionality unchanged (verified through manual testing)
- Code quality metrics improved (measurable reduction in complexity/duplication)
---
## Refactoring Plan (3 Phases)
### Phase 1: Analysis & Preparation
**Baseline Capture:**
- [ ] Run existing test suite → Record pass/fail count (baseline for Phase 3)
- [ ] Document current behavior:
- Take screenshots of key UI states (if UI changes)
- Capture API responses for key endpoints (if backend changes)
- Record timing benchmarks (if performance-sensitive)
- [ ] Identify all affected tests:
- `rg "ClassName|functionName" tests/` → Find tests that exercise refactored code
- Review test files to understand test coverage
- [ ] Create backup branch (git branch backup/refactor-[feature-name])
**Best Practices Research:**
- [ ] Research DRY patterns (MCP Ref, Context7, WebSearch)
- Query: "DRY principle [language] best practices 2024"
- Find established patterns for consolidating duplicated code
- [ ] Research KISS simplification (if applicable)
- Query: "simplify [over-engineered pattern] [language]"
- Find simpler alternatives to current implementation
- [ ] Review project guides (CLAUDE.md, docs/guides/)
- Verify patterns referenced in Story Technical Notes
- Ensure refactoring aligns with project standards
**Risk Assessment:**
- [ ] Identify high-risk refactorings (core business logic, critical paths)
- [ ] Plan incremental approach (small changes, test after each)
- [ ] Document rollback plan (if refactoring fails)
### Phase 2: Refactoring Execution
**Execute refactorings in priority order (HIGH → MEDIUM → LOW):**
**Issue 1: [HIGH Priority]**
- [ ] [Step 1: Specific action - e.g., "Create shared utility function in utils/validators.py"]
- [ ] [Step 2: Specific action - e.g., "Replace 3 duplicates in api/routes/*.py"]
- [ ] [Step 3: Specific action - e.g., "Add unit tests for new utility function"]
- [ ] Run tests after Issue 1 fix (verify no regression)
**Issue 2: [MEDIUM Priority]**
- [ ] [Step 1: Specific action]
- [ ] [Step 2: Specific action]
- [ ] Run tests after Issue 2 fix
**Issue 3: [LOW Priority]**
- [ ] [Step 1: Specific action]
- [ ] [Step 2: Specific action]
- [ ] Run tests after Issue 3 fix
**Incremental Approach:**
- Fix one issue at a time
- Run tests after each fix (catch regressions immediately)
- Commit after each successful fix (git commit -m "refactor: fix [issue]")
- If any test fails → STOP, analyze, fix refactoring (not test)
### Phase 3: Regression Verification
**Verify functionality unchanged:**
- [ ] **Run test suite again:**
- Compare with Phase 1 baseline
- MUST match exactly (same pass/fail count, same test names)
- If ANY test fails → Refactoring introduced bug, MUST fix
- [ ] **Compare behavior with baseline:**
- API responses MUST be identical (diff outputs)
- UI screenshots MUST match (visual regression)
- Timing within 5% of baseline (performance not degraded)
- [ ] **Manual smoke testing:**
- Test main user flows (verify no behavior change)
- Use `scripts/tmp_[story_id].sh` if exists (from manual testing)
- Document any unexpected behavior
- [ ] **Quality gates:**
- Type checking passes (mypy/TypeScript)
- Linting passes (ruff/ESLint)
- No new warnings introduced
**If verification fails:**
- [ ] Analyze failure root cause (refactoring bug vs test bug)
- [ ] Fix refactoring (preferred) OR update test (only if test was wrong)
- [ ] Re-run Phase 3 verification
---
## Regression Testing Strategy
> [!WARNING]
> Refactoring NEVER changes functionality. If tests fail after refactoring → Implementation error.
### Baseline Capture (Phase 1)
**Test Suite Baseline:**
```bash
# Run full test suite, capture output
pytest -v > baseline_tests.txt # or npm test, etc.
# Record metrics
Total tests: [X]
Passed: [X]
Failed: [X]
Skipped: [X]
```
**Behavior Baseline (for critical functionality):**
```bash
# Capture API responses
curl -X GET $BASE_URL/api/endpoint > baseline_api_response.json
# Capture UI state (if applicable)
# Screenshot key pages, record element states
```
**Performance Baseline (if performance-sensitive):**
```bash
# Record timing benchmarks
pytest --benchmark-only > baseline_benchmarks.txt
```
### Verification Protocol (Phase 3)
**Step 1: Test Suite Comparison**
- Run test suite again → Compare with baseline
- **Expected:** Exact match (same tests pass/fail)
- **If mismatch:** STOP, analyze failure, fix refactoring
**Step 2: Behavior Comparison**
- Capture API responses again → Diff with baseline
- **Expected:** Identical responses (diff shows no changes)
- **If different:** STOP, analyze, fix refactoring
**Step 3: Performance Comparison**
- Run benchmarks again → Compare with baseline
- **Expected:** Within 5% of baseline timing
- **If degraded >5%:** Analyze, optimize refactoring
### Failure Handling
**If ANY test fails after refactoring:**
1. **STOP immediately** - Do NOT proceed with additional refactorings
2. **Analyze root cause:**
- Read test failure message
- Identify which refactoring caused failure
- Determine if refactoring introduced bug OR test needs update
3. **Fix refactoring (preferred approach):**
- Revert last change: `git revert HEAD`
- Re-analyze issue, apply safer refactoring
- Run tests again
4. **Update test (only if test was wrong):**
- Verify test expectation was incorrect (not refactoring bug)
- Update test assertions/mocks
- Document why test update needed (in commit message)
5. **Re-run Phase 3 verification**
**Tools:**
- Test framework: pytest/jest/vitest (auto-detected in Phase 1)
- Diff tools: `diff`, `jq` (for JSON), screenshot comparison
- Performance: pytest-benchmark, Lighthouse (if UI)
---
## Code Simplification Principles
Apply these principles during Phase 2 refactoring (from Claude Code PR Toolkit `code-simplifier` agent):
### 1. Preserve Functionality (HARD RULE)
**Rule:** NEVER change what code does - only HOW it does it.
- ❌ **Forbidden:** Change outputs, modify behavior, alter features
- ✅ **Allowed:** Change structure, consolidate logic, rename variables
- ✅ **Verification:** All existing tests MUST pass after refactoring
**Example:**
```python
# WRONG: Changed behavior
def validate_email(email):
# Before: allowed @gmail.com and @yahoo.com
# After: ONLY allows @gmail.com (BEHAVIOR CHANGED - FORBIDDEN!)
return email.endswith('@gmail.com')
# CORRECT: Same behavior, refactored
def validate_email(email):
# Before: inline validation in 3 places
# After: extracted to shared function (SAME BEHAVIOR - ALLOWED!)
allowed_domains = ('@gmail.com', '@yahoo.com')
return email.endswith(allowed_domains)
```
### 2. Apply Project Standards
**Follow CLAUDE.md coding standards:**
- ES modules with proper imports
- Explicit type annotations
- Proper error handling (avoid try/catch when possible)
- Consistent naming conventions
**Example:**
```typescript
// Before: Non-standard
const getUser = (id) => { ... }
// After: Project standard (explicit types, function keyword)
function getUser(id: string): User | null { ... }
```
### 3. Enhance Clarity
**Reduce complexity, improve readability:**
- ✅ Reduce nesting (extract nested logic to functions)
- ✅ Eliminate redundant code (DRY principle)
- ✅ Clear names (intent-revealing variable/function names)
- ✅ Consolidate related logic (group cohesive operations)
- ✅ Remove unnecessary comments (self-documenting code)
- ✅ Avoid nested ternaries (use switch/if-else for multiple conditions)
**Example:**
```python
# Before: Nested and unclear
if user:
if user.active:
if user.verified:
return user.data
return None
# After: Clear and flat
if not user or not user.active or not user.verified:
return None
return user.data
```
### 4. Maintain Balance (DON'T Over-Simplify)
**Avoid extreme simplification:**
- ❌ Don't reduce clarity for brevity (explicit > compact)
- ❌ Don't combine too many concerns (single responsibility)
- ❌ Don't remove helpful abstractions
- ❌ Don't prioritize "fewer lines" over readability
**Example:**
```javascript
// WRONG: Over-simplified (hard to understand)
const r = u?.a && u?.v ? u?.d : null;
// CORRECT: Clear and explicit
if (!user || !user.active || !user.verified) {
return null;
}
return user.data;
```
### 5. Focus Scope
**Only refactor what's in scope:**
- ✅ Refactor code identified in Code Quality Issues section
- ✅ Refactor closely related code (within same module/class)
- ❌ Don't expand scope beyond identified issues
- ❌ Don't refactor unrelated files
**Example:**
```
Issue: Duplicate validation in api/routes/users.py and api/routes/auth.py
✅ Refactor: Extract validation to utils/validators.py
✅ Refactor: Update imports in both route files
❌ Don't refactor: Other unrelated routes (outside scope)
```
---
## Acceptance Criteria
**Given** current implementation has code quality issues
**When** refactoring is applied according to Refactoring Plan
**Then** all issues are resolved AND functionality is preserved
**Specific Checks:**
- [ ] **DRY:** No code duplication remains (verified with grep/rg for repeated patterns)
- [ ] **KISS:** Solutions simplified where possible (removed over-engineering)
- [ ] **YAGNI:** No unused features remain (verified with grep/rg, dead code eliminated)
- [ ] **Architecture:** Clean layer boundaries (no violations of project patterns)
- [ ] **Guides:** Implementation aligns with project guides (CLAUDE.md, docs/guides/)
- [ ] **Regression:** All existing tests pass (Phase 3 verification successful)
- [ ] **Behavior:** Functionality unchanged (manual testing confirms same behavior)
- [ ] **Quality Gates:** Type checking + linting pass (no new warnings)
---
## Affected Components
### Implementation Files to Refactor
- `path/to/component1` - [What will be refactored: e.g., "Extract duplicate validation logic"]
- `path/to/component2` - [What will be refactored: e.g., "Simplify state management"]
- `path/to/component3` - [What will be refactored: e.g., "Remove unused OAuth 1.0 implementation"]
### Tests to Update (ONLY if refactoring breaks them)
- `tests/path/test_file1` - [Why update needed: e.g., "Mock signatures changed"]
- `tests/path/test_file2` - [Why update needed: e.g., "Assertions need adjustment"]
### Documentation to Update
- `README.md` - [What to update: e.g., "Remove references to old pattern"]
- `ARCHITECTURE.md` - [What to update: e.g., "Update component diagram"]
- `docs/guides/[guide].md` - [What to update: e.g., "Update code examples"]
---
## Existing Code Impact
### Refactoring Required
**Component 1: [Component Name]**
- **File:** `path/to/file`
- **What:** [Specific refactoring action - e.g., "Extract duplicate validation to shared utility"]
- **Why:** [Reason - e.g., "DRY violation: same logic in 3 places"]
- **Risk:** [HIGH/MEDIUM/LOW] - [Risk explanation]
**Component 2: [Component Name]**
- **File:** `path/to/file`
- **What:** [Refactoring action]
- **Why:** [Reason]
- **Risk:** [Level]
### Tests to Update (ONLY Existing Tests Affected)
**SCOPE:** ONLY list existing tests that may break due to refactoring (signature changes, mock updates, etc.).
DO NOT create new tests here. New tests were created in Story's final test task by ln-350-story-test-planner.
**Examples of valid test updates:**
- Mock/stub updates when function signatures change
- Assertion updates when internal structure changes
- Import path updates when files moved
**Test Suite 1:**
- **File:** `tests/path/test_file`
- **Why Affected:** [Reason - e.g., "Function signature changed from (a, b) to (config)"]
- **Update Needed:** [Specific change - e.g., "Update mock to use new signature"]
### Documentation to Update
- `docs/file.md` - [Existing docs to update - e.g., "Update architecture diagram"]
- `README.md` - [What to update - e.g., "Remove references to deprecated pattern"]
---
## Definition of Done
### Refactoring Completion
- [ ] All problems from Code Quality Issues section resolved
- [ ] All refactorings from Phase 2 executed successfully
- [ ] Code follows DRY/KISS/YAGNI/SOLID principles
- [ ] Architecture clean (proper layer boundaries)
- [ ] Guides followed (project patterns applied)
### Regression Verification
- [ ] **All existing tests pass** (Phase 3 verification successful)
- [ ] Test suite matches Phase 1 baseline (same pass/fail count)
- [ ] Functionality unchanged (manual testing confirms)
- [ ] Behavior matches baseline (API responses, UI states identical)
- [ ] Performance within 5% of baseline (no degradation)
### Quality Gates
- [ ] Type checking passes (mypy/TypeScript)
- [ ] Linting passes (ruff/ESLint)
- [ ] No new warnings introduced
### Documentation
- [ ] Code changes documented (commit messages describe refactorings)
- [ ] README.md updated (if public API/patterns changed)
- [ ] ARCHITECTURE.md updated (if component structure changed)
- [ ] Guides updated (if refactoring changes recommended patterns)
### Review
- [ ] Code reviewed by team member (if applicable)
- [ ] Refactoring approach approved (architecture alignment)
---
**Template Version:** 2.0.0 (Expanded with Code Quality Issues, Refactoring Plan, Regression Testing Strategy, Code Simplification Principles)
**Last Updated:** 2025-11-13

146
skills/ln-311-task-creator/references/task_template_implementation.md Normal file
View File

@@ -0,0 +1,146 @@
# Task Title
<!-- Task Size Guideline: Optimal 3-5 hours development time (atomic, testable unit). Too small < 3h → combine with related work. Too large > 8h → decompose further. -->
<!-- SCOPE: Implementation tasks ONLY. DO NOT create new tests in this task.
New tests (E2E/Integration/Unit) are created separately by ln-350-story-test-planner after manual testing passes.
This task may update existing tests if implementation changes break them. -->
**Epic:** [Epic N - Epic Name](link) *(optional)*
**User Story:** [USXXX Story Name](link) *(parent task - this task will have parentId=USXXX)*
**Related:** TEAM-XX, TEAM-YY
---
## Context
### Current State
- What exists now?
- What's the problem or limitation?
### Desired State
- What should exist after completion?
- What benefits will this bring?
---
## Implementation Plan
### Phase 1: [Description]
- [ ] Step 1
- [ ] Step 2
### Phase 2: [Description]
- [ ] Step 1
- [ ] Step 2
### Phase 3: [Description]
- [ ] Step 1
- [ ] Step 2
---
## Technical Approach
### Recommended Solution
**Library/Framework:** [name] v[version] ([stability: LTS/stable/beta])
**Documentation:** [official docs URL]
**Standards compliance:** [RFC/spec if applicable, e.g., RFC 6749 for OAuth 2.0]
### Key APIs
**Primary methods:**
- `[method_signature]` - [purpose and when to use]
- `[method_signature]` - [purpose and when to use]
- `[method_signature]` - [purpose and when to use]
**Configuration:**
- `[parameter]`: [value/type] - [purpose and impact]
- `[parameter]`: [value/type] - [purpose and impact]
### Implementation Pattern
**Core logic:**
```pseudocode
[High-level pseudocode showing main integration flow]
[Focus on HOW to integrate library/API, not full business logic]
[5-10 lines maximum - this is a guide, not implementation]
```
**Integration points:**
- **Where:** [file/module path where integration happens]
- **How:** [dependency injection / direct import / middleware / decorator / etc.]
- **When:** [startup / request handler / background task / etc.]
### Why This Approach
- [Reason 1: Standards compliance or industry best practice reference]
- [Reason 2: Performance/Security/Maintainability/Team familiarity benefit]
### Patterns Used
- [Pattern 1] - [purpose in this context]
- [Pattern 2] - [purpose in this context]
### Known Limitations
- [Limitation 1: e.g., no async support, memory constraints] - [workaround or mitigation if any]
- [Limitation 2: e.g., compatibility issue, deprecated feature] - [impact on implementation]
### Alternatives Considered
- **Alternative 1:** [name] - [why rejected: outdated/over-engineered/non-standard/lacking feature]
- **Alternative 2:** [name] - [why rejected: performance/complexity/compatibility]
---
**SCOPE NOTE:** This Technical Approach should be 200-300 words max. Focus on KEY APIs (2-5 methods) and integration points, NOT exhaustive API documentation. This specification guides implementation without prescribing every detail. Executor discovers full implementation specifics during execution.
---
## Acceptance Criteria
- [ ] **Given** [context] **When** [action] **Then** [result]
- [ ] **Given** [context] **When** [action] **Then** [result]
- [ ] **Given** [context] **When** [action] **Then** [result]
---
## Affected Components
### Implementation
- `path/to/file` - Changes
### Documentation (REQUIRED in this task)
- `README.md` - Feature documentation
- `docs/api.md` - API updates
---
## Existing Code Impact
### Refactoring Required
- `path/to/file` - What needs refactoring and why
### Tests to Update (ONLY Existing Tests Affected by This Task)
**SCOPE:** ONLY list existing tests that break due to implementation changes (refactoring, logic updates).
DO NOT create new tests here. New tests are created by ln-350-story-test-planner after manual testing.
**Examples of valid updates:**
- Mock/stub changes when function signatures change
- Assertion updates when return values change
- Test data updates when validation logic changes
- `tests/path/test_file` - Why this existing test needs updates
### Documentation to Update
- `docs/file.md` - Existing docs to update
---
## Definition of Done
- [ ] All acceptance criteria met
- [ ] All existing code refactored (no backward compatibility / legacy code left)
- [ ] All existing tests updated (if any were affected by implementation changes)
- [ ] NO new tests created (new tests are in Story's final test task by ln-350-story-test-planner)
- [ ] Documentation updated
- [ ] Code reviewed
---
**Template Version:** 6.0.1 (Renamed from task_template_universal.md to clarify scope: implementation tasks only)
**Last Updated:** 2025-11-13

542
skills/ln-311-task-creator/references/test_task_template.md Normal file
View File

@@ -0,0 +1,542 @@
# Tests for Story: [Story Title]
**User Story:** [USXXX Story Name](link) *(parent task - this is the FINAL task of Story)*
**Epic:** [Epic N - Epic Name](link)
---
## Context
### Story Goal
[Story statement from parent: As a... I want... So that...]
### Implemented Features
List of completed implementation tasks in this Story:
- [API-XX: Task Name](link) - What was implemented
- [API-YY: Task Name](link) - What was implemented
### What to Test
All business logic implemented across Story Tasks:
- Components/modules added or modified
- Integration points established
- Business flows enabled
---
## Risk Priority Matrix
**Reference:** See `risk_based_testing_guide.md` for detailed methodology
**Priority Formula:** Priority = Business Impact (1-5) × Probability of Failure (1-5)
| Scenario | Business Impact | Probability | Priority | Test Type | Notes |
|----------|----------------|-------------|----------|-----------|-------|
| [Scenario from manual testing] | [1-5] | [1-5] | [1-25] | E2E/Integration/Unit/SKIP | [Reason for decision] |
| [Scenario from manual testing] | [1-5] | [1-5] | [1-25] | E2E/Integration/Unit/SKIP | [Reason for decision] |
**Test Limits:** 2-5 E2E (baseline 2), 0-8 Integration, 0-15 Unit per Story (**realistic goal: 2-7 total**, hard limit: 28)
**Minimum Viable Testing Philosophy:**
- Start with 2 baseline E2E tests per endpoint (positive + negative)
- Add tests #3+ ONLY with critical justification: "Why does this test OUR business logic (not framework/library/database)?"
- Auto-trim to 7 tests if plan exceeds realistic goal (keep 2 baseline E2E + top 5 Priority)
**Principles:**
- ✅ Prioritize by business risk (money, security, data corruption) over coverage metrics
- ✅ Test OUR code ONLY (not frameworks/libraries/external systems/database queries)
- ✅ Anti-Duplication: If 2 baseline E2E cover logic, SKIP unit test
- ✅ Anti-Framework: If testing Prisma/Express/bcrypt behavior → SKIP
- ✅ Fast feedback: Unit (ms) → Integration (seconds) → E2E (tens of seconds)
- ✅ Focus on critical paths (Priority ≥15), not blanket coverage
**Decision Criteria:**
- Priority ≥15 → MUST test (if tests OUR logic)
- Priority 9-14 → SHOULD test if not already covered AND tests OUR logic
- Priority ≤8 → SKIP (manual testing sufficient)
---
## E2E Tests (2-5 max)
**BASELINE (ALWAYS): 2 E2E tests per endpoint**
- Test 1: Positive scenario (happy path validating main AC)
- Test 2: Negative scenario (critical error handling)
**ADDITIONAL (Tests 3-5): ONLY if Priority ≥15 AND critical justification provided**
Test complete user journeys through the system. Each test beyond baseline 2 MUST justify: "Why does this test OUR business logic (not framework/library/database)?"
**Type:** [API E2E / UI E2E] *(depending on application type)*
### [Critical Scenario 1]: [User Journey Name] (Priority [XX])
**From Manual Testing:** [Link to AC or edge case in manual test results]
**Business Impact:** [1-5] - [Why critical: money/security/core flow]
**Probability of Failure:** [1-5] - [Why risky: complexity/external API/new tech]
**Priority:** [Business Impact × Probability] = [Result]
**Test Flow (copied from manual testing):**
1. **Setup:** [Initial state/preconditions from manual testing]
2. **Step 1:** [User action from curl/puppeteer] → **Verify:** [Expected result verified manually]
3. **Step 2:** [User action] → **Verify:** [Expected result]
4. **Step 3:** [User action] → **Verify:** [Final outcome]
5. **Cleanup:** [Teardown actions]
**Test:**
- [ ] `test_e2e_[scenario_name]` - Full journey from start to finish
**Anti-Duplication Check:**
- ✅ This E2E test is necessary because: [Unique business value not covered by other tests]
### [Critical Scenario 2]: [User Journey Name] (Priority [XX])
**From Manual Testing:** [Link to AC or edge case]
**Business Impact:** [1-5]
**Probability of Failure:** [1-5]
**Priority:** [Result]
**Test Flow:**
1. **Setup:** [Initial state]
2. **Actions & Verifications:** [Step-by-step user journey]
3. **Cleanup:** [Teardown]
**Test:**
- [ ] `test_e2e_[scenario_name]` - Description
**Anti-Duplication Check:**
- ✅ This E2E test is necessary because: [Reason]
### Standards
- [ ] **BASELINE: 2 E2E tests per endpoint (positive + negative) - ALWAYS**
- [ ] **ADDITIONAL: Tests 3-5 ONLY with critical justification**
- [ ] Maximum 5 E2E tests per Story (hard limit)
- [ ] All scenarios Priority ≥15
- [ ] **Each test beyond baseline 2 has documented justification: "Why does this test OUR business logic?"**
- [ ] E2E tests run in < 2 minutes total
- [ ] Test against stable environment (staging/test)
- [ ] Based on ACTUAL manual testing results (not theoretical scenarios)
- [ ] Clean up test data after execution
- [ ] **No tests for framework/library/database behavior** (trust Prisma/Express/PostgreSQL)
---
## Integration Tests (0-8 max)
**DEFAULT: 0 Integration tests** (2 baseline E2E tests cover full stack by default)
**ADD ONLY if:** E2E doesn't cover interaction completely AND Priority ≥15 AND critical justification provided
Test OUR business logic with REAL internal dependencies. **ONLY Priority ≥15 interactions NOT fully covered by 2 baseline E2E.** Each integration test MUST justify: "Why does this test OUR integration logic (not framework/library behavior)?"
### [Integration Point 1]: [Layer Interaction] (Priority [XX])
**Scope:** [Layer A] → [Layer B] → [Layer C] (e.g., API → Service → Repository → DB)
**Why Integration Test Needed:**
- E2E test covers happy path, but need to verify: [Transaction rollback / Error handling / Concurrency]
- Business Impact: [1-5] - [Reason]
- Probability: [1-5] - [Reason]
- Priority: [Result]
**Tests:**
- [ ] `test_[flow]_integration` - Verifies complete data flow through layers
- **Given:** [Setup: real DB with test data]
- **When:** [Action: call Layer A]
- **Then:** [Verify: data correctly flows and persists in DB]
**Use Real:**
- Database (test instance)
- Filesystem (temp directory)
- Internal services
**Use Mocks:**
- External API calls
- Email/SMS services
- Payment gateways
**Anti-Duplication Check:**
- ✅ This integration test adds value because: [E2E doesn't test error scenario / E2E doesn't test concurrent requests]
### [Integration Point 2]: [Description] (Priority [XX])
**Scope:** [Description of integration]
**Why Integration Test Needed:**
- [Reason E2E insufficient]
- Priority: [Result]
**Tests:**
- [ ] `test_[integration_scenario]` - What interaction this verifies
**Anti-Duplication Check:**
- ✅ Adds value because: [Reason]
### Standards
- [ ] **DEFAULT: 0 Integration tests** (2 baseline E2E cover full stack)
- [ ] Maximum 8 integration tests per Story (hard limit)
- [ ] All scenarios Priority ≥15
- [ ] **Each integration test has documented justification: "Why does this test OUR integration logic?"**
- [ ] Use test database (not production)
- [ ] Clean up after each test (rollback/truncate)
- [ ] All integration tests run in < 30 seconds total
- [ ] Skip if 2 baseline E2E already validate end-to-end
- [ ] **No tests for framework/library integrations** (Prisma client, TypeORM, Express app behavior)
---
## Unit Tests (0-15 max)
**DEFAULT: 0 Unit tests** (2 baseline E2E tests cover simple logic by default)
**ADD ONLY for:** Complex business logic with Priority ≥15 AND critical justification provided
Test individual components in isolation with all dependencies mocked. **ONLY complex business logic with Priority ≥15.** Each unit test MUST justify: "Why does this test OUR complex business logic (not library/framework/database behavior)?"
**MANDATORY SKIP - DO NOT create unit tests for:**
- ❌ Simple CRUD operations (already covered by 2 baseline E2E)
- ❌ Framework code (Express middleware, React hooks, FastAPI dependencies)
- ❌ Library functions (bcrypt hashing, jsonwebtoken signing, axios requests)
- ❌ Database queries (Prisma findMany, TypeORM query builder, SQL joins)
- ❌ Getters/setters or simple property access
- ❌ Trivial conditionals (`if (user) return user.name`, `status === 'active'`)
- ❌ Pass-through functions (wrappers without logic)
- ❌ Performance/load testing (throughput, latency, stress tests, scalability)
### [Component/Module Name 1]: [Complex Business Logic Function] (Priority [XX])
**File:** `path/to/component`
**Why Unit Test Needed:**
- Function: [Financial calculation / Security logic / Complex algorithm]
- Business Impact: [1-5] - [Money/Security/Data]
- Probability: [1-5] - [Complexity/Edge cases]
- Priority: [Result]
**Business scenarios to test:**
- [ ] `test_[function]_happy_path` - Main business scenario
- [ ] `test_[function]_edge_case_[discovered_in_manual_testing]` - Edge case from manual testing (Priority ≥9)
- [ ] `test_[function]_error_handling_[business_impact_4_or_5]` - Error with high business impact
**Mocks needed:**
- [Dependency 1]: Mock behavior
- [Dependency 2]: Mock behavior
**Anti-Duplication Check:**
- ✅ E2E doesn't fully exercise: [Edge case X / Error condition Y]
### [Component/Module Name 2]: [Another Complex Function] (Priority [XX])
**File:** `path/to/component`
**Why Unit Test Needed:**
- [Reason - complexity/business impact]
- Priority: [Result]
**Business scenarios to test:**
- [ ] `test_[scenario]` - Description of what this test verifies and WHY (business value)
**Mocks needed:**
- [Dependency]: Mock behavior
**Anti-Duplication Check:**
- ✅ Not covered by E2E because: [Reason]
### Standards
- [ ] **DEFAULT: 0 Unit tests** (2 baseline E2E cover simple logic)
- [ ] Maximum 15 unit tests per Story (hard limit)
- [ ] **Each unit test has documented justification: "Why does this test OUR complex business logic?"**
- [ ] All tests run in < 5 seconds total
- [ ] No external dependencies (DB, filesystem, network)
- [ ] Each test independent (can run in any order)
- [ ] Only test complex business logic (Priority ≥15): financial calculations, security algorithms, complex business rules
- [ ] Skip if 2 baseline E2E already exercise all branches
- [ ] **No tests for library/framework/database behavior** (bcrypt, jwt, Prisma, axios)
## Critical Path Coverage
**Focus:** All Priority ≥15 scenarios tested, NOT blanket coverage percentage
**What MUST be tested (Priority ≥15):**
- [ ] All Acceptance Criteria from Story (verified in manual testing)
- [ ] Money-related scenarios (payments, refunds, pricing calculations)
- [ ] Security-critical flows (authentication, authorization, data access)
- [ ] Data integrity scenarios (transactions, rollbacks, concurrent updates)
- [ ] Core business flows (user cannot complete primary use case)
- [ ] High-risk edge cases discovered in manual testing (Priority ≥15)
**What SHOULD be tested (Priority 9-14) if not covered by E2E:**
- [ ] Medium-risk edge cases from manual testing
- [ ] Secondary business flows
- [ ] Error scenarios with Business Impact 3-4
**What to SKIP (Priority ≤8):**
- ❌ Simple CRUD operations (E2E covers these)
- ❌ Framework code (Express, React, Prisma)
- ❌ Third-party libraries (not our code)
- ❌ Trivial getters/setters
- ❌ Cosmetic bugs (color, spacing)
- ❌ Minor UX issues (button state)
- ❌ Scenarios already validated by manual testing with low business impact
- ❌ Performance/load testing (requires separate infrastructure and specialized tools)
**Coverage Expectations:**
- Coverage % is a metric, NOT a goal
- 40% coverage with 2 baseline E2E + Priority ≥15 scenarios tested → **ACCEPTABLE**
- 60% coverage with all Priority ≥15 scenarios tested → **EXCELLENT**
- 90% coverage but includes framework/library tests → **UNACCEPTABLE** (remove framework tests)
- 90% coverage but payment flow not tested → **UNACCEPTABLE**
**Acceptance Criteria:**
- [ ] **Given** All Priority ≥15 scenarios identified **When** tests executed **Then** all scenarios PASS
- [ ] **Given** Test limits (2-5 E2E, 0-8 Integration, 0-15 Unit) **When** validation **Then** within realistic goal 2-7 (hard limit: 28)
- [ ] **Given** Tests duplicate logic **When** review **Then** consolidate or remove duplication
- [ ] **Given** Scenario has Priority ≤14 **When** review **Then** skip test (manual testing sufficient)
- [ ] **Given** Test validates framework/library/database **When** review **Then** remove test (not OUR code)
---
## Definition of Done
- [ ] **2 baseline E2E tests implemented and passing (positive + negative) - ALWAYS**
- [ ] All additional E2E tests implemented and passing (0-3 additional, all Priority ≥15 with justification)
- [ ] All integration tests implemented and passing (0-8 max, all Priority ≥15 with justification)
- [ ] All unit tests implemented and passing (0-15 max, all Priority ≥15 with justification)
- [ ] **Total tests: 2-7 (realistic goal) or 2-28 (hard limit)**
- [ ] **Each test beyond baseline 2 has documented justification: "Why does this test OUR business logic?"**
- [ ] All Priority ≥15 scenarios from manual testing covered
- [ ] No flaky tests (all tests pass consistently on multiple runs)
- [ ] Test execution time acceptable (Unit <5s, Integration <30s, E2E <2min)
- [ ] **All tests validate OUR code ONLY (not frameworks/libraries/database queries)**
- [ ] **No tests for Prisma/Express/bcrypt/jwt/axios/PostgreSQL behavior**
- [ ] Anti-duplication verified: each test adds unique business value
- [ ] Skipped scenarios documented with Priority justification (Priority ≤14 or framework/library behavior)
- [ ] Documentation updated (tests/README.md if needed)
---
## Existing Tests to Fix/Update
**Tests affected by changes:**
Before adding new tests, update existing tests that might have broken due to logic changes in this Story.
### [Test File/Suite 1]: [Test Name or Path]
**File:** `path/to/test/file`
**Why Affected:**
- [Explain how Story implementation changed behavior tested by this test]
- [E.g., "Changed validation logic in API endpoint requires updated mock responses"]
**Required Fixes:**
- [ ] Update test setup/fixtures
- [ ] Update expected values/assertions
- [ ] Update mocked dependencies
- [ ] Verify test passes after fix
### [Test File/Suite 2]: [Test Name or Path]
**File:** `path/to/test/file`
**Why Affected:**
- [Reason this existing test needs updates]
**Required Fixes:**
- [ ] [Specific fix needed]
### Standards
- [ ] All existing tests identified and reviewed
- [ ] All affected tests fixed BEFORE adding new tests
- [ ] Entire existing test suite passes
- [ ] No tests temporarily disabled/skipped without justification
- [ ] Changes documented in commit message
---
## Infrastructure Changes
**Package Updates:**
### Testing Dependencies
**Packages to Add/Update:**
- `[package-name]@[version]` - [Why needed: new test framework feature / testing library for new component]
- `[package-name]@[version]` - [Why needed]
**package.json changes:**
```json
{
"devDependencies": {
"[package-name]": "[version]"
},
"scripts": {
"[test-script]": "[command]"
}
}
```
### Docker/Compose Updates
**Dockerfile changes (if needed):**
- [ ] Add test dependencies layer
- [ ] Update base image for test environment
- [ ] Add environment variables for testing
**docker-compose.yml changes (if needed):**
- [ ] Add test database service
- [ ] Add test environment configuration
- [ ] Add test volumes/networks
### Test Configuration
**Configuration files to update:**
- [ ] `jest.config.js` / `vitest.config.ts` / `pytest.ini` - [What to configure]
- [ ] `.env.test` - [Environment variables for testing]
- [ ] Test database setup scripts
- [ ] CI/CD pipeline configuration
### Standards
- [ ] All package versions specified (no `^` or `~` for test deps)
- [ ] Packages compatible with existing stack
- [ ] Docker changes tested locally
- [ ] Test configuration committed to repository
---
## Documentation Updates
**Files requiring documentation updates:**
### tests/README.md
**Updates needed:**
- [ ] Document new test commands (`npm test`, `npm run test:e2e`, etc.)
- [ ] Explain test structure changes (if any)
- [ ] Document test data setup/teardown
- [ ] Add troubleshooting section for common test failures
- [ ] Update test coverage expectations
### README.md (Main)
**Updates needed:**
- [ ] Feature documentation (what was tested and how)
- [ ] Setup instructions (if new dependencies added)
- [ ] Testing section (how to run tests for this feature)
- [ ] Known limitations (if any scenarios skipped with Priority ≤8)
### CHANGELOG.md
**Entry to add:**
```markdown
## [Version] - 2025-11-03
### Tested
- [Feature/Story tested]
- Test coverage: [X] E2E, [Y] Integration, [Z] Unit tests
- All Priority ≥15 scenarios covered
```
### Other Documentation
**Additional docs to update (if applicable):**
- [ ] API documentation (if endpoints tested)
- [ ] Architecture documentation (if test patterns changed)
- [ ] Deployment guide (if test infrastructure changed)
### Standards
- [ ] All documentation in English
- [ ] Code examples tested and working
- [ ] Links to relevant files/resources
- [ ] No outdated information remains
---
## Legacy Code Cleanup
**Workarounds/Hacks to Remove:**
### [File/Module 1]: [Legacy Code Item]
**File:** `path/to/file`
**What to Remove:**
```
// Lines or code blocks to remove
[old code here]
```
**Why Safe to Remove:**
- [Justification: functionality now covered by new implementation]
- [Verification: tests confirm new code provides same behavior]
- [Risk assessment: Low - deprecated since [date/version]]
**Verification:**
- [ ] All tests pass after removal
- [ ] No references remain in codebase (grep check)
- [ ] Feature functionality preserved
### [File/Module 2]: [Backward Compatibility Code]
**File:** `path/to/file`
**What to Remove:**
- [Backward compatibility shims no longer needed]
- [Deprecated patterns replaced by new approach]
**Why Safe to Remove:**
- [Reason: all clients migrated to new API]
- [Verification: usage analytics show zero calls]
**Verification:**
- [ ] Tests confirm removal safe
- [ ] Documentation updated (no references to old pattern)
### Deprecated Patterns
**Patterns to Replace:**
**Old Pattern:**
```
[Example of old pattern in codebase]
```
**New Pattern (implemented in this Story):**
```
[Example of new pattern]
```
**Files Using Old Pattern:**
- [ ] `path/to/file1` - Replace with new pattern
- [ ] `path/to/file2` - Replace with new pattern
**Verification:**
- [ ] All instances found (grep/search)
- [ ] All replaced with new pattern
- [ ] Tests updated to use new pattern
- [ ] Old pattern documented as deprecated (if can't remove immediately)
### Dead Code
**Code to Remove:**
- [ ] Unused functions/classes: [List]
- [ ] Commented-out code blocks: [Where]
- [ ] Unreachable code paths: [Where]
**Verification Method:**
- [ ] Static analysis (unused imports, unused variables)
- [ ] Test coverage (uncovered code blocks)
- [ ] Code review (manual inspection)
### Standards
- [ ] All removals justified with clear reasoning
- [ ] Tests confirm functionality preserved
- [ ] No references remain (grep verification)
- [ ] Removals documented in commit message
- [ ] High-risk removals discussed with team before execution
---
**Template Version:** 3.0.0 (Added sections 8-11: Test Fixes + Infrastructure + Documentation + Cleanup)
**Last Updated:** 2025-11-03

65
skills/ln-312-task-replanner/SKILL.md Normal file
View File

@@ -0,0 +1,65 @@
---
name: ln-312-task-replanner
description: Updates ALL task types (implementation/refactoring/test). Compares IDEAL plan vs existing tasks, categorizes KEEP/UPDATE/OBSOLETE/CREATE, applies changes in Linear and kanban.
---
# Universal Task Replanner
Worker that re-syncs existing tasks to the latest requirements for any task type.
## Purpose & Scope
- Load full existing task descriptions from Linear
- Compare them with orchestrator-provided IDEAL plan (implementation/refactoring/test)
- Decide operations (KEEP/UPDATE/OBSOLETE/CREATE) and execute
- Drop NFR items; only functional scope remains
- Update Linear issues and kanban_board.md accordingly
## Invocation (who/when)
- ln-310-story-decomposer: REPLAN mode when implementation tasks already exist.
- ln-340-story-quality-gate: Refactoring task needs updates after new findings.
- ln-350-story-test-planner: Test task needs updates after manual testing changes.
- Not user-invoked directly.
## Inputs
- Common: `taskType`, teamId, Story data (id/title/description with AC, Technical Notes, Context), existingTaskIds.
- Implementation: idealPlan (1-6 tasks), guideLinks.
- Refactoring: codeQualityIssues, refactoringPlan, affectedComponents.
- Test: manualTestResults, testPlan (E2E 2-5, Integration 0-8, Unit 0-15, Priority ≤15), infra/doc/cleanup items.
## Workflow (concise)
1) Load templates per taskType from ln-311-task-creator/references and fetch full existing task descriptions.
2) Normalize both sides (IDEAL vs existing sections) and run replan algorithm to classify KEEP/UPDATE/OBSOLETE/CREATE.
3) Present summary (counts, titles, key diffs). Confirmation required if running interactively.
4) Execute operations in Linear: update descriptions, cancel obsolete, create missing, preserve parentId/state team.
5) Update kanban_board.md: remove canceled, add new tasks under Story in Backlog.
6) Return operations summary with URLs and warnings.
## Type Rules (must hold after update)
| taskType | Hard rule | What to enforce |
|----------|-----------|-----------------|
| implementation | No new test creation | Updated/created tasks must not introduce test creation text |
| refactoring | Regression strategy required | Issues + severity, 3-phase plan, regression strategy, preserve functionality |
| test | Risk-based limits | Priority ≤15 scenarios; E2E 2-5, Integration 0-8, Unit 0-15, Total 10-28; no framework/library/DB tests |
## Critical Notes
- Foundation-First ordering from IDEAL plan is preserved; do not reorder.
- Language preservation: keep existing task language (EN/RU).
- No code snippets; keep to approach/steps/AC/components.
- If Story reality differs (component exists, column exists), propose Story correction to orchestrator.
## Definition of Done
- Existing tasks loaded and parsed with correct template.
- IDEAL plan vs existing compared; operations classified.
- Type validation passed for all updated/created tasks.
- Operations executed in Linear (updates, cancels, creations) with parentId intact.
- kanban_board.md updated (Backlog) with correct Epic/Story/indentation.
- Summary returned (KEEP/UPDATE/OBSOLETE/CREATE counts, URLs, warnings).
## Reference Files
- Templates: `../ln-311-task-creator/references/task_template_implementation.md`, `../ln-311-task-creator/references/refactoring_task_template.md`, `../ln-311-task-creator/references/test_task_template.md`
- Replan algorithm: `references/replan_algorithm.md`
- Kanban format: `docs/tasks/kanban_board.md`
---
Version: 6.0.0 (Condensed replan flow and validation table)
Last Updated: 2025-11-26

127
skills/ln-312-task-replanner/diagram.html Normal file
View File

@@ -0,0 +1,127 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>ln-312-task-replanner - Universal Replanner</title>
<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
<link rel="stylesheet" href="../shared/css/diagram.css">
</head>
<body>
<div class="container">
<header>
<h1>ln-312-task-replanner</h1>
<p class="subtitle">Universal Replanner - Worker v1.0.0</p>
</header>
<div class="info-box">
<h2>Overview</h2>
<ul>
<li><strong>Purpose:</strong> Universal replanner worker for updating existing tasks when Story requirements change</li>
<li><strong>Pattern:</strong> Worker v1.0.0 - Invoked by orchestrator (x-task-manager) via Skill tool with taskType parameter</li>
<li><strong>Templates:</strong>
<ul>
<li><code>implementation</code> → task_template_implementation.md (7 sections)</li>
<li><code>refactoring</code> → refactoring_task_template.md (7 sections)</li>
<li><code>test</code> → test_task_template.md (11 sections)</li>
</ul>
</li>
<li><strong>Comparison Logic:</strong> Match tasks by goal/purpose, categorize changes</li>
<li><strong>Input:</strong> IDEAL plan + existing task IDs from orchestrator</li>
<li><strong>Output:</strong> Operations summary + diffs + URLs → return to orchestrator</li>
</ul>
</div>
<div class="info-box">
<h2>Operation Categories</h2>
<div class="operation-box">
<h3>🟢 KEEP</h3>
<p>Goals match, no changes needed → Task unchanged</p>
</div>
<div class="operation-box">
<h3>🟡 UPDATE</h3>
<p>Goals match, but AC/approach changed → Modify description with type-specific validation</p>
</div>
<div class="operation-box">
<h3>🔴 OBSOLETE</h3>
<p>No match in IDEAL (feature removed) → Cancel task in Linear + add comment</p>
</div>
<div class="operation-box">
<h3>🔵 CREATE</h3>
<p>In IDEAL but no existing match → New task needed with type-specific validation</p>
</div>
</div>
<div class="diagram-container">
<div class="mermaid">
graph TD
Start([Invoked by orchestrator<br/>taskType parameter]) --> SelectTemplate{Select Template<br/>by taskType}
SelectTemplate -->|implementation| T1[task_template_implementation.md<br/>7 sections]
SelectTemplate -->|refactoring| T2[refactoring_task_template.md<br/>7 sections]
SelectTemplate -->|test| T3[test_task_template.md<br/>11 sections]
T1 --> Phase1
T2 --> Phase1
T3 --> Phase1
Phase1[Phase 1: Load Existing Tasks<br/>Full descriptions from Linear<br/>Parse sections by template]
Phase1 --> Phase2[Phase 2: Compare IDEAL vs Existing<br/>Match by goal<br/>Categorize operations]
Phase2 --> Categorize{Determine operations}
Categorize -->|Goals match<br/>No changes| KEEP[KEEP:<br/>Task unchanged]
Categorize -->|Goals match<br/>AC/approach changed| UPDATE[UPDATE:<br/>Modify description]
Categorize -->|No match in IDEAL<br/>Feature removed| OBSOLETE[OBSOLETE:<br/>Cancel task]
Categorize -->|In IDEAL<br/>No existing match| CREATE[CREATE:<br/>New task needed]
KEEP --> Phase3[Phase 3: Show Operations Summary<br/>+ Diffs for UPDATE<br/>+ Warnings for edge cases]
UPDATE --> Phase3
OBSOLETE --> Phase3
CREATE --> Phase3
Phase3 --> Phase4{Phase 4: User Confirmation}
Phase4 -->|"confirm"| Phase5[Phase 5: Execute Operations]
Phase4 -->|Other input| Abort([Abort: Return to orchestrator])
Phase5 --> Step1[Step 1: UPDATE tasks<br/>Type-specific validation]
Step1 --> Step2[Step 2: OBSOLETE tasks<br/>Cancel in Linear<br/>Add comments]
Step2 --> Step3[Step 3: CREATE tasks<br/>Generate + create<br/>Type-specific validation]
Step3 --> Step4[Step 4: Update kanban_board.md<br/>Remove canceled<br/>Add new tasks]
Step4 --> Success([SUCCESS<br/>Return operations summary<br/>+ URLs + warnings])
style Start fill:#e1f5fe
style Success fill:#c8e6c9
style Abort fill:#fff9c4
style SelectTemplate fill:#e1bee7
style T1 fill:#c8e6c9
style T2 fill:#fff3e0
style T3 fill:#ffcdd2
style KEEP fill:#c8e6c9
style UPDATE fill:#fff3e0
style OBSOLETE fill:#ffcdd2
style CREATE fill:#e1bee7
style Categorize fill:#fff3e0
style Phase4 fill:#fff3e0
</div>
</div>
<footer>
<p>ln-312-task-replanner v1.0.0 | Universal Replanner Pattern | Mermaid.js</p>
</footer>
</div>
<script>
mermaid.initialize({
startOnLoad: true,
theme: 'default',
flowchart: {
useMaxWidth: true,
htmlLabels: true,
curve: 'basis'
}
});
</script>
</body>
</html>

665
skills/ln-312-task-replanner/references/replan_algorithm.md Normal file
View File

@@ -0,0 +1,665 @@
# Task Replan Algorithm
Detailed comparison logic for x-task-coordinator REPLAN MODE. This algorithm determines which operations (KEEP/UPDATE/OBSOLETE/CREATE) to perform when existing tasks are found for a Story.
## Overview
When a Story's requirements change and tasks already exist, x-task-coordinator compares the IDEAL task decomposition (from Phase 2) with existing tasks (from Linear) to determine the minimal set of operations needed.
**Key Principle**: The IDEAL plan from Phase 2 is the source of truth. Existing tasks are compared against this plan.
## Inputs
### Phase 2 Output: IDEAL Task Plan
Result from Story analysis (runs BEFORE checking existing tasks):
**Structure**:
- Task count: 1-4 (based on Story complexity)
- Task titles: Descriptive names (e.g., "Implement token generation endpoint")
- Task goals: Derived from Story AC
- Foundation-First ordering: Database → Repository → Service → API
- Estimate per task: 3-5 hours
- Guide links: From Story Technical Notes
**Example IDEAL Plan**:
```
IDEAL TASK PLAN (3 tasks, 12h total):
1. Implement token generation endpoint
- Goal: Handle POST /auth/token with credentials
- AC: AC1 (valid credentials), AC2 (invalid credentials)
- Estimate: 4h
2. Add token validation middleware
- Goal: Validate JWT tokens in protected routes
- AC: AC3 (valid token), AC4 (expired token)
- Estimate: 3h
3. Create token refresh logic
- Goal: Implement token refresh mechanism
- AC: AC5 (refresh with valid refresh token)
- Estimate: 5h
Foundation-First order: ✓
Guide links: [JWT Best Practices](../../docs/guides/jwt-best-practices.md)
```
### Linear Data: Existing Tasks
From `list_issues(parentId=Story.id)`:
**Structure**:
- Task IDs: Linear issue IDs (e.g., "EP7_01", "EP7_02")
- Titles: Task titles
- Descriptions: Full 7 sections (Context, Implementation Plan, Technical Approach, AC, Components, Existing Code Impact, DoD)
- Status: Todo, In Progress, To Review, Done, Canceled
**Example Existing Tasks**:
```
EXISTING TASKS (3 found):
1. EP7_01: Implement token generation endpoint
Status: Done
Created: 2025-11-01
AC: AC1, AC2
2. EP7_02: Validate JWT tokens
Status: Todo
Created: 2025-11-05
AC: AC3 (missing AC4!)
3. EP7_03: Cache tokens in Redis
Status: Todo
Created: 2025-11-06
AC: AC6 (caching requirement)
```
## Comparison Algorithm
### Step 1: Match by Goal
For EACH task in IDEAL plan:
1. **Extract goal** from IDEAL plan task title and description
2. **Search existing tasks** for similar goal:
- Fuzzy match on titles (e.g., "token generation" matches "Implement token generation")
- Check AC overlap (do they cover same Story AC?)
- Look for key terms (e.g., "validation", "refresh", "generation")
3. **Result**:
- If **match found** → Candidate for KEEP or UPDATE
- If **no match** → Mark for CREATE
For EACH existing task:
1. **Extract goal** from existing task title and AC
2. **Search IDEAL plan** for similar goal
3. **Result**:
- If **match found** → Candidate for KEEP or UPDATE
- If **no match** → Mark for OBSOLETE
### Step 2: Determine Operations
For EACH existing task:
#### KEEP Operation
**Criteria** (ALL must be true):
- ✅ Task exists in IDEAL plan (goal matches)
- ✅ AC unchanged (compare Story AC sections referenced in task)
- ✅ Implementation approach still valid (guide links, patterns)
- ✅ Status: Any except Done or Canceled
- ✅ No structural changes needed (Affected Components same)
**Action**: None (task is already correct)
**Example**:
```
EP7_01: Implement token generation endpoint
- IDEAL plan has: "Token generation endpoint" (AC1, AC2)
- Existing task has: AC1, AC2
- Status: Done
→ KEEP (task matches IDEAL plan, already complete)
```
#### UPDATE Operation
**Criteria** (ANY must be true):
- ⚠️ Task in IDEAL plan BUT AC changed
- New AC added to Story
- Existing AC modified (conditions changed)
- AC removed from task scope
- ⚠️ Technical approach changed
- New guide links added to Story
- Architecture patterns updated
- Technology stack changed
- ⚠️ Affected components changed
- New files to modify
- Different layers involved
**Constraints**:
- ✅ Status: Todo or Backlog ONLY
- ❌ If In Progress/To Review → WARNING, manual review needed (don't auto-update)
- ❌ If Done → WARNING, never update Done tasks
**Action**: `update_issue(id, description=new_description)`
**Example**:
```
EP7_02: Validate JWT tokens
- IDEAL plan has: "Token validation middleware" (AC3, AC4)
- Existing task has: AC3 ONLY (AC4 missing!)
- Status: Todo
→ UPDATE (AC4 "Handle expired tokens" added to Story)
Changes to apply:
- Update AC section: Add AC4 scenario
- Update Implementation Plan: Add expiration check phase
- Update Technical Approach: Reference token expiration guide
```
#### OBSOLETE Operation
**Criteria** (ALL must be true):
- ❌ Task NOT in IDEAL plan (no matching goal)
- ❌ Feature removed from Story AC
- ❌ OR functionality merged into different task
**Constraints**:
- ✅ Status: Todo or Backlog ONLY
- ❌ If In Progress/To Review → WARNING, manual review needed (don't auto-cancel)
- ❌ If Done → WARNING, never obsolete Done tasks (work was completed)
**Action**:
```
update_issue(id, state="Canceled")
```
Add comment: "Task canceled due to Story replan. Feature removed from requirements."
**Example**:
```
EP7_03: Cache tokens in Redis
- IDEAL plan does NOT have: Caching task
- Story AC6 (caching requirement) REMOVED
- Status: Todo
→ OBSOLETE (caching is no longer in scope)
Action: Cancel task, preserve history
```
#### CREATE Operation
**Criteria** (ALL must be true):
- ✨ Task in IDEAL plan
- ✨ No existing task matches goal
- ✨ New requirement added to Story
**Action**: `create_issue(title, description, parentId=Story.id, ...)` (same as CREATE MODE)
**Example**:
```
IDEAL plan has: "Email validation" (NEW AC6)
- No existing task for email validation
- New requirement added to Story
→ CREATE (new task needed)
Generate:
- Title: "EP7_04: Validate email format in registration"
- Description: Full 7 sections
- AC: AC6 from Story
- parentId: Story.id
```
### Step 3: Handle Edge Cases
#### Edge Case 1: Obsolete Task In Progress
**Scenario**: Task is marked OBSOLETE but status is In Progress or To Review.
**Problem**: Someone is actively working on this task, auto-canceling would waste work.
**Action**:
```
WARNING: "Task EP7_03 is In Progress but no longer in IDEAL plan. Manual review needed."
- Do NOT auto-cancel
- Show in operations summary with ⚠️ warning
- Let user decide:
- Complete the task and cancel later?
- Cancel now and abandon work?
- Merge work into different task?
```
#### Edge Case 2: UPDATE Task To Review
**Scenario**: Task needs UPDATE (AC changed) but status is To Review (awaiting review).
**Problem**: Task already completed and awaiting review, updating would invalidate the review.
**Action**:
```
WARNING: "Task EP7_02 is To Review but AC changed. Review may need to restart."
- Show diff (old AC vs new AC)
- Let user decide:
- Update now (review must restart)?
- Wait for review to complete, then update?
- Cancel task and create new one?
```
#### Edge Case 3: IDEAL Plan Differs from Done Tasks
**Scenario**: IDEAL plan significantly differs from completed Done tasks.
**Problem**: Work was completed under old requirements, new requirements are different.
**Action**:
```
WARNING: "Story requirements changed significantly. Done tasks may need follow-up work."
- NEVER update or cancel Done tasks (preserve completed work)
- If new requirements conflict with Done work → CREATE new task to address discrepancy
- Example:
- Done: "EP7_01: Token generation with JWT"
- IDEAL: "Token generation with OAuth2" (different approach!)
- Action: CREATE "EP7_04: Migrate token generation to OAuth2"
```
#### Edge Case 4: Multiple Tasks Match Same IDEAL Goal
**Scenario**: Two existing tasks both match same IDEAL plan goal.
**Problem**: Duplicate work, unclear which to keep.
**Action**:
```
WARNING: "Multiple tasks match same IDEAL goal. Manual consolidation needed."
- EP7_02: "Validate JWT tokens" (Todo)
- EP7_05: "Add token validation" (In Progress)
- Both match IDEAL: "Token validation middleware"
Let user decide:
- Keep EP7_05 (In Progress), obsolete EP7_02?
- Merge both into one task?
```
#### Edge Case 5: AC Count Mismatch
**Scenario**: IDEAL plan has 5 AC, but distributed differently across tasks than existing tasks.
**Problem**: AC reassignment between tasks.
**Action**:
```
EXAMPLE:
IDEAL Plan:
- Task 1: AC1, AC2, AC3 (endpoint)
- Task 2: AC4, AC5 (middleware)
Existing Tasks:
- EP7_01: AC1, AC2 (endpoint) - Done
- EP7_02: AC3, AC4, AC5 (middleware) - Todo
Operations:
- EP7_01: KEEP (Done, matches AC1, AC2)
- EP7_02: UPDATE (AC3 moved to Task 1, remove from EP7_02)
- BUT AC3 implementation may be in EP7_02 code!
- WARNING: "AC3 reassigned. Manual code review needed."
```
## Example Scenarios
### Scenario 1: AC Change (UPDATE)
**Story**: US001 OAuth Authentication
**Change**: AC4 "Handle expired tokens" ADDED to Story
**IDEAL Plan** (Phase 2):
```
1. Token generation endpoint (AC1, AC2)
2. Token validation middleware (AC3, AC4) ← AC4 NEW!
3. Token refresh logic (AC5)
```
**Existing Tasks**:
```
1. EP7_01: Token generation (AC1, AC2) - Done
2. EP7_02: Validate tokens (AC3 ONLY) - Todo
3. EP7_03: Token refresh (AC5) - In Progress
```
**Comparison**:
```
EP7_01 vs IDEAL Task 1:
- Goals match: ✓ (token generation)
- AC match: ✓ (AC1, AC2)
- Status: Done
→ KEEP
EP7_02 vs IDEAL Task 2:
- Goals match: ✓ (token validation)
- AC match: ✗ (AC3 only, AC4 missing)
- Status: Todo
→ UPDATE (add AC4)
EP7_03 vs IDEAL Task 3:
- Goals match: ✓ (token refresh)
- AC match: ✓ (AC5)
- Status: In Progress
→ KEEP (In Progress, don't interfere)
```
**Operations Summary**:
```
KEEP: 2 tasks (EP7_01 Done, EP7_03 In Progress)
UPDATE: 1 task (EP7_02 add AC4)
OBSOLETE: 0 tasks
CREATE: 0 tasks
```
**Diff for EP7_02 UPDATE**:
```diff
## Acceptance Criteria
- **Given** valid JWT token in Authorization header
**When** request is made to protected route
**Then** request proceeds with authenticated user context
+ **Given** expired JWT token in Authorization header
+ **When** request is made to protected route
+ **Then** return 401 Unauthorized with "Token expired" message
```
### Scenario 2: Feature Removed (OBSOLETE)
**Story**: US001 OAuth Authentication
**Change**: Caching requirement REMOVED from Story (AC6 deleted)
**IDEAL Plan** (Phase 2):
```
1. Token generation endpoint (AC1, AC2)
2. Token validation middleware (AC3, AC4)
3. Token refresh logic (AC5)
# NO caching task (AC6 removed)
```
**Existing Tasks**:
```
1. EP7_01: Token generation (AC1, AC2) - Done
2. EP7_02: Validate tokens (AC3, AC4) - Todo
3. EP7_03: Cache tokens in Redis (AC6) - Todo ← AC6 REMOVED!
```
**Comparison**:
```
EP7_01 → KEEP (matches IDEAL Task 1)
EP7_02 → KEEP (matches IDEAL Task 2)
EP7_03 → OBSOLETE (no matching goal in IDEAL plan, AC6 removed)
```
**Operations Summary**:
```
KEEP: 2 tasks
UPDATE: 0 tasks
OBSOLETE: 1 task (EP7_03 caching)
CREATE: 0 tasks
```
**Action for EP7_03**:
```
update_issue(
id="EP7_03",
state="Canceled"
)
Add comment:
"Task canceled due to Story replan. Caching requirement (AC6) removed from Story.
Original AC6: Cache JWT tokens in Redis with 1-hour TTL.
Reason: Simplified authentication flow, removed caching complexity."
```
### Scenario 3: New Feature Added (CREATE)
**Story**: US002 User Profile
**Change**: NEW AC4 "Upload avatar" ADDED to Story
**IDEAL Plan** (Phase 2):
```
1. Create profile endpoint (AC1)
2. Update profile endpoint (AC2, AC3)
3. Upload avatar (AC4) ← NEW!
```
**Existing Tasks**:
```
1. EP8_01: Create profile (AC1) - Done
2. EP8_02: Update profile (AC2, AC3) - In Progress
# NO avatar task
```
**Comparison**:
```
EP8_01 → KEEP (matches IDEAL Task 1, Done)
EP8_02 → KEEP (matches IDEAL Task 2, In Progress)
IDEAL Task 3 → CREATE (no existing task for avatar upload)
```
**Operations Summary**:
```
KEEP: 2 tasks
UPDATE: 0 tasks
OBSOLETE: 0 tasks
CREATE: 1 task (avatar upload)
```
**New Task EP8_03**:
```
Title: "EP8_03: Implement avatar upload for user profile"
Description: (7 sections)
- Context: Users need to upload profile pictures
- Implementation Plan: File upload, validation, storage, URL generation
- Technical Approach: Multipart form data, S3/local storage, image processing
- AC: AC4 from Story (upload, size limits, format validation)
- Affected Components: src/api/profile.ts, src/services/storage.ts
- Existing Code Impact: Add storage service, update profile model
- DoD: Upload works, validation enforced, images stored securely
Estimate: 4 hours
parentId: US002
```
### Scenario 4: Scope Reduction (Multiple OBSOLETE)
**Story**: US003 Payment Integration
**Change**: PayPal and Refund APIs REMOVED from scope (simplify to Stripe only)
**IDEAL Plan** (Phase 2):
```
1. Stripe integration (AC1, AC2)
2. Payment webhook (AC3)
# PayPal removed
# Refund API removed
```
**Existing Tasks**:
```
1. EP9_01: Stripe integration (AC1, AC2) - Todo
2. EP9_02: Payment webhook (AC3) - In Progress
3. EP9_03: PayPal integration (AC4) - Todo ← REMOVED!
4. EP9_04: Refund API (AC5) - Todo ← REMOVED!
```
**Comparison**:
```
EP9_01 → KEEP (matches IDEAL Task 1)
EP9_02 → KEEP (matches IDEAL Task 2, In Progress)
EP9_03 → OBSOLETE (PayPal removed)
EP9_04 → OBSOLETE (Refund removed)
```
**Operations Summary**:
```
KEEP: 2 tasks
UPDATE: 0 tasks
OBSOLETE: 2 tasks (EP9_03 PayPal, EP9_04 Refund)
CREATE: 0 tasks
```
**Warning**:
```
⚠️ EP9_02 (Payment webhook) is In Progress.
Ensure webhook handler still works with reduced scope (Stripe only, no PayPal events).
Manual review recommended.
```
### Scenario 5: Complex Reassignment
**Story**: US004 Search Functionality
**Change**: AC3 "Pagination" moved from "Search results" task to "Search API" task
**IDEAL Plan** (Phase 2):
```
1. Search API with pagination (AC1, AC2, AC3) ← AC3 moved here!
2. Search results display (AC4, AC5)
# AC3 was in Task 2, now in Task 1
```
**Existing Tasks**:
```
1. EP10_01: Search API (AC1, AC2) - Done
2. EP10_02: Search results (AC3, AC4, AC5) - Todo ← AC3 should move!
```
**Comparison**:
```
EP10_01 vs IDEAL Task 1:
- Goals match: ✓
- AC match: ✗ (AC3 missing, now required)
- Status: Done
→ KEEP (Done, don't update)
→ WARNING: AC3 pagination should be in API but implemented in results!
EP10_02 vs IDEAL Task 2:
- Goals match: ✓
- AC match: ✗ (AC3 should not be here)
- Status: Todo
→ UPDATE? (remove AC3, keep AC4/AC5)
→ WARNING: AC3 code may be in EP10_02, refactoring needed!
```
**Operations Summary**:
```
KEEP: 1 task (EP10_01 Done)
UPDATE: 1 task (EP10_02 remove AC3 reference)
CREATE: 1 task (NEW: Refactor pagination to API)
OBSOLETE: 0 tasks
WARNINGS:
- AC reassignment detected (AC3: results → API)
- EP10_01 is Done, cannot update
- Code refactoring required (move pagination logic)
- Manual intervention needed
```
**Recommended Action**:
```
Create NEW task:
EP10_03: "Refactor pagination from results to API"
- Goal: Move pagination logic from search results component to search API endpoint
- Reason: AC3 reassignment after EP10_01 completion
- Implementation: Extract pagination from EP10_02, integrate into API
- Testing: Ensure backward compatibility, update existing tests
- Estimate: 3 hours
```
## Best Practices
### 1. Be Conservative with Updates
- **Prefer CREATE over UPDATE** when in doubt
- Updating tasks can invalidate work in progress
- Creating new tasks preserves existing work
### 2. Respect Status
- **Never auto-update In Progress/To Review tasks**
- **Never auto-cancel In Progress/To Review tasks**
- **Never update/cancel Done tasks**
- Show warnings, let user decide
### 3. Preserve History
- Use `state="Canceled"` for obsolete tasks (don't delete)
- Add comments explaining why task was canceled
- Reference removed AC numbers and reasons
### 4. Handle AC Reassignment Carefully
- AC moving between tasks is complex
- Code may be in wrong task
- Requires manual refactoring
- Create explicit refactoring tasks
### 5. Show Clear Diffs
- For UPDATE operations, show before/after
- Highlight added/removed AC
- Show technical approach changes
- Make review easy for user
### 6. Warn About Work Loss
- If canceling task with partial work → warning
- If updating task with code changes → warning
- If Done task conflicts with new requirements → create follow-up task
### 7. Foundation-First Validation
- Ensure IDEAL plan respects Foundation-First execution order
- If replan changes order → warning
- Dependencies should flow correctly (Database before Repository before Service before API)
## Output Format
### Operations Summary
```
REPLAN SUMMARY for US001:
IDEAL PLAN (from Story analysis):
1. Token generation endpoint (AC1, AC2)
2. Token validation middleware (AC3, AC4) ← AC4 ADDED!
3. Email validation (NEW AC6) ← NEW!
EXISTING TASKS:
✓ EP7_01: Token generation endpoint
Status: Done
Operation: KEEP (matches plan, already Done)
⚠ EP7_02: Token validation middleware
Status: Todo
Operation: UPDATE (AC4 added to Story)
Changes:
- Add AC4: Handle expired token scenario
- Update Implementation Plan with expiration check
- Update Technical Approach: Reference token expiration guide
✗ EP7_03: Cache tokens in Redis
Status: Todo
Operation: OBSOLETE (caching removed from Story)
Action: Cancel task (state="Canceled")
NEW TASKS:
+ EP7_04: Email validation
Goal: Validate email format in registration
Estimate: 3 hours
AC: New AC6 from Story
OPERATIONS: 1 keep, 1 update, 1 cancel, 1 create
WARNINGS:
- EP7_02 will be updated (AC changed)
Type "confirm" to execute all operations.
```
---
**Version:** 1.0.0
**Last Updated:** 2025-11-10

119
skills/ln-320-story-validator/SKILL.md Normal file
View File

@@ -0,0 +1,119 @@
---
name: ln-320-story-validator
description: Reviews Stories/Tasks against 2025 standards before approval (Backlog -> Todo). Auto-fixes issues, validates structure, optimizes via YAGNI/KISS/SOLID. Auto-discovers team/config.
---
# Story Verification Skill
Critically review and auto-fix Stories and Tasks against 2025 standards and project architecture before execution.
## Purpose & Scope
- Validate Story plus child Tasks against industry standards and project patterns
- Auto-fix detected issues (structure, solution, workflow, quality) before approval
- Approve Story after fixes (Backlog -> Todo) and link any missing guides
- Strip or re-home Non-Functional Requirements; keep only functional scope in Story/Tasks
## When to Use
- Reviewing Stories before approval (Backlog -> Todo)
- Validating implementation path across Story and Tasks
- Ensuring standards, architecture, and solution fit
- Optimizing or correcting proposed approaches
## Workflow Overview
### Phase 1: Discovery & Loading
- Auto-discover configuration: Team ID (docs/tasks/kanban_board.md), project docs (CLAUDE.md), epic from Story.project
- Load metadata only: Story ID/title/status/labels, child Task IDs/titles/status/labels
- Expect 3-8 implementation tasks; record parentId for filtering
- Rationale: keep loading light; full descriptions arrive in Phase 2
### Phase 2: Critical Solution Review
- Load full Story description (all 8 sections) when analysis starts
- Standards first (priority): Industry/RFCs -> Security -> 2025 best practices -> KISS/YAGNI/DRY within standards
- Challenge approach: prefer proven standards over custom work; keep language as-is (EN/RU)
- Documentation check and creation triggers (pattern keywords, package versions, technology choices); invoke ln-321-guide-creator / ln-323-manual-creator / ln-322-adr-creator if missing
- Verify against codebase reality before edits; if Story is outdated, auto-correct via Linear update
- Reporting rule: when principles are violated, explain why with best-practice references and propose concrete fixes, not just list names
### Phase 3: Comprehensive Auto-Fix
- Always auto-fix; no "Needs Work" path. Follow execution order: Structural (1-4) -> Solution (5-8) -> Workflow (9-12) -> Scope & Quality (13-16)
- Use Auto-Fix Actions table below as the authoritative checklist; keep sequential task validation to avoid truncation
- Test mention: ensure Test Strategy section exists but keep it empty here; do not plan coverage or execution at this stage
### Phase 4: Approve & Notify
- Set Story + all Tasks to Todo (Linear); update kanban_board.md with APPROVED marker and move items from Backlog to Todo keeping hierarchy
- Add Linear comment summarizing fixes, created docs (paths), ADRs/manuals/guides, and any TODO warnings
- Verification summary display: Story verdict (always Approved -> Todo), changes, linked docs, warnings; Tasks table with changes and guide links
- Any principle violations in reports must include rationale, best-practice reference, and recommended remediation steps
## Auto-Fix Actions Reference
| # | What it checks | Auto-fix actions | Notes/Evidence |
|---|----------------|------------------|----------------|
|1 Story Structure|8 sections per story_template_universal.md in order|Add/reorder sections and subsections with TODO placeholders; update Linear; preserve language|Skip if Done/Canceled or older than 30 days|
|2 Tasks Structure|Each Task has 7 sections in order|Load each Task full description sequentially; add/reorder sections with placeholders; update Linear and comment; preserve language|Sequential per task; skip if Done/Canceled or older than 30 days|
|3 Story Statement|As a/I want/So that clarity|Rewrite using persona (Context), capability (Technical Notes), value (Success Metrics); update Linear and comment|-|
|4 Acceptance Criteria|Given/When/Then, 3-5 items, edge/error coverage|Normalize AC to G/W/T; add missing edge/error cases; update Linear and comment|-|
|5 Solution Optimization|2025-best approach aligned with prior patterns|Rewrite Technical Notes and Tasks if better approach exists; cite modern patterns/libs; reference prior Story context; add TODO for duplicates/conflicts|Log rationale in Linear|
|6 Library & Version|Current stable versions; prefer built-ins|Update versions in Technical Notes/Tasks; replace custom helpers with built-ins; update Linear and comment|List versions checked|
|7 Test Strategy|Section exists but remains empty now|Ensure Test Strategy section present; leave empty with note that testing is planned later by ln-350; do not add coverage details|Mention "testing handled later; not evaluated in this phase"|
|8 Documentation Integration|No standalone doc tasks|Remove doc-only tasks; fold doc updates into implementation tasks and DoD; update Linear and comment|-|
|9 Story Size & Granularity|3-8 tasks; 3-5h each|If <3 tasks invoke ln-310-story-decomposer; if >8 add TODO to split; flag tasks <3h or >8h with TODO; reload metadata and update kanban_board.md|Comment creation source|
|10 Test Task Cleanup|No premature test tasks|Cancel/remove tasks labeled as tests or named test/comprehensive/final; remove from Story/kanban; comment that testing tasks appear later|Testing not executed now|
|11 YAGNI|No premature features|Move speculative items to Out of Scope/Future; update Technical Notes/Tasks; comment rationale|-|
|12 KISS|Simplest solution within standards|Replace over-engineered parts with simpler options unless standards require otherwise; update Linear with reasoning|Standard overrides simplicity|
|13 Documentation Links|Technical Notes reference docs|Add "Related Documentation" subsection; link guides/manuals/ADRs by path; update Linear|Use created/existing paths|
|14 Foundation-First Order|Task order DB -> Repo -> Service -> API -> Frontend|Reorder Implementation Tasks and note execution order; update Linear and comment|-|
|15 Code Quality Basics|No magic values; config approach defined|Add TODOs for constants/config/env creds; describe config management in Technical Notes; update Linear|Warn in summary if TODOs remain|
|16 Industry Standards|Compliance with RFCs/protocols|Check docs in guides/manuals/ADRs; if missing invoke creators; document compliance and links; if none apply, state explicit reason; update Linear|Evidence required: doc path or worker call; log skip reason if applicable|
## Self-Audit Protocol (Mandatory)
- Before marking any criterion, answer its Self-Audit question, provide concrete evidence (doc path, Linear comment link, worker result), and record in `checkpoints/{STORY_ID}_verification_log.md`. No evidence -> no completion.
| # | Self-Audit Question | Required Evidence |
|---|---------------------|-------------------|
|1|Validated all 8 Story sections in order?|Section list|
|2|Loaded full description for each Task?|Task validation count|
|3|Statement in As a/I want/So that?|Quoted statement|
|4|AC are G/W/T and testable?|AC count and format|
|5|Challenged "best for 2025"?|Reasoning logged|
|6|All versions current stable?|Version list checked|
|7|Test Strategy kept empty for now?|Note that testing is deferred|
|8|Docs integrated, no standalone tasks?|Integration evidence|
|9|Task count 3-8 and 3-5h?|Task count/sizes|
|10|No premature test tasks?|Search result|
|11|Only current-scope features?|Scope review|
|12|Simplest approach within standards?|Simplicity justification|
|13|All relevant guides linked?|Guide paths|
|14|Tasks ordered DB->Repo->Service->API?|Task order list|
|15|Hardcoded values handled?|TODO/config evidence|
|16|Standards verified via docs/worker?|Doc path or worker result|
## Definition of Done
- Verification log created from template with answered Self-Audit for all 16 criteria and evidence
- Phase 1: auto-discovery done; Story + Tasks metadata loaded; task count checked
- Phase 2: full Story parsed; standards researched; doc gaps filled via creators; codebase reality verified; reports explain violations with best-practice references and fixes
- Phase 3: criteria 1-16 auto-fixed in order; Test Strategy section present but empty; test tasks removed; guide links inserted
- Phase 4: Story/Tasks set to Todo; kanban_board.md updated with APPROVED marker and hierarchy; Linear comment added with fixes, docs, ADRs/manuals/guides, TODO warnings; summary table shown
## Example Workflows
- **Outdated library:** Detect old version, update to current stable in Technical Notes/Tasks, document change, approve.
- **OAuth violation:** Replace custom endpoints with RFC-compliant `/token` flow, add spec reference, update Tasks/Technical Notes, approve.
- **Missing tasks:** If <3 tasks, run ln-310-story-decomposer, reload tasks, reorder Foundation-First, update kanban and comments, approve.
## Reference Files
- Templates: `../ln-220-story-coordinator/references/story_template_universal.md`, `../ln-311-task-creator/references/task_template_implementation.md`
- Checklists: `references/verification_checklist.md`, `references/verification_log_template.md`
- Testing methodology (for later phases): `../ln-350-story-test-planner/references/risk_based_testing_guide.md`
- Linear integration: `../ln-210-epic-coordinator/references/linear_integration.md`
---
Version: 12.1.0 (Condensed guidance, tabled auto-fix actions, clarified testing deferral and violation reporting)
Last Updated: 2025-11-26

84
skills/ln-320-story-validator/diagram.html Normal file
View File

@@ -0,0 +1,84 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>ln-320-story-validator - State Diagram</title>
<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
<link rel="stylesheet" href="../shared/css/diagram.css">
</head>
<body>
<div class="container">
<header>
<h1>✅ ln-320-story-validator</h1>
<p class="subtitle">Story Verifier - State Diagram</p>
</header>
<div class="info-box">
<h3>📋 Overview</h3>
<ul>
<li><strong>Purpose:</strong> Auto-fix and approve Stories (8 sections) and Tasks (7 sections) against industry standards</li>
<li><strong>Verdict:</strong> ALWAYS approves after auto-fixing ALL 16 verification criteria (no "Needs Work" path)</li>
<li><strong>State Transition:</strong> Backlog → Todo (Story + ALL Tasks)</li>
<li><strong>Structure:</strong> 4 phases (Discovery & Loading → Critical Review → Auto-Fix Groups A/B/C/D → Approve & Notify)</li>
</ul>
</div>
<div class="diagram-container">
<div class="mermaid">
graph TD
Start([Start: Verify Story]) --> Phase1[Phase 1: Discovery & Loading<br/>Team ID + project docs<br/>Load Story FULL + Tasks metadata<br/>Validate task breakdown 3-8 tasks]
Phase1 --> Phase2[Phase 2: Critical Solution Review<br/>Standards Hierarchy PRIORITY 1-4]
subgraph Standards [Standards Compliance & Solution Review]
S1[Check industry standards FIRST<br/>OAuth 2.0 REST OpenAPI RFCs<br/>PRIORITY 1]
S1 --> S2[Challenge approach<br/>Best way in 2025?<br/>Research best practices]
S2 --> S3{Documentation<br/>gaps detected?}
S3 -->|None| S9[Continue to Phase 3]
S3 -->|Pattern<br/>trigger| S6[Auto-create Guide<br/>ln-321-guide-creator<br/>HOW to implement]
S3 -->|Package+version<br/>trigger| S7[Auto-create Manual<br/>ln-323-manual-creator<br/>HOW to use library]
S3 -->|Decision<br/>trigger| S8[Auto-create ADR<br/>ln-322-adr-creator<br/>WHY we decided]
S6 --> S10[Save doc paths<br/>for Phase 3 #13]
S7 --> S10
S8 --> S10
S9 --> Phase3
S10 --> Phase3
end
Phase2 --> S1
Phase3[Phase 3: Comprehensive Auto-Fix<br/>16 Verification Criteria #1-#16]
subgraph FixGroups [Auto-Fix Groups A → B → C → D]
GA[Group A: Structural Fixes<br/>#1 Story Structure 8 sections<br/>#2 Tasks Structure 7 sections sequential<br/>#3 Story Statement As a/I want/So that<br/>#4 Acceptance Criteria Given/When/Then]
GA --> GB[Group B: Solution Optimization<br/>#5 Industry Standards RFC compliance<br/>#6 Solution 2025 best practices<br/>#7 Library & Version current stable<br/>#13 Documentation Links insertion]
GB --> GC[Group C: Workflow Optimization<br/>#9 Test Strategy Risk-Based<br/>#10 Test Task Cleanup remove premature<br/>#11 Documentation Integration<br/>#12 Foundation-First Execution]
GC --> GD[Group D: Scope & Quality<br/>#13 Story Size 3-8 tasks x-task-manager<br/>#14 YAGNI Violations<br/>#15 KISS Violations<br/>#16 Code Quality config management]
end
Phase3 --> GA
GD --> Phase4
Phase4[Phase 4: Approve & Notify<br/>Story + ALL Tasks → Todo<br/>kanban_board.md ✅ APPROVED<br/>Approval comment + optional warning<br/>Summary table display]
Phase4 --> End([End: Story ALWAYS Approved])
classDef discovery fill:#E3F2FD,stroke:#1976D2,stroke-width:2px
classDef processing fill:#FFF9C4,stroke:#F57C00,stroke-width:2px
classDef action fill:#C8E6C9,stroke:#388E3C,stroke-width:2px
class Phase1 discovery
class Phase2,S1,S2,S3,Phase3,GA,GB,GC,GD processing
class Phase4 action
</div>
</div>
<footer>
<p>ln-320-story-validator v10.0.0 | 4 phases · 16 auto-fix criteria · NO "Needs Work" path - ALWAYS approves after fixes</p>
</footer>
</div>
<script>
mermaid.initialize({ startOnLoad: true, theme: 'default', flowchart: { useMaxWidth: true, htmlLabels: true, curve: 'basis' } });
</script>
</body>
</html>

457
skills/ln-320-story-validator/references/verification_checklist.md Normal file
View File

@@ -0,0 +1,457 @@
# Story Verification Checklist
Complete checklist for verifying Story and all its Tasks before approval.
**CRITICAL PRINCIPLE:** This skill ALWAYS auto-fixes all issues detected. Never leave Story in Backlog with feedback - fix and approve.
## Mandatory Checks (Auto-Fix Actions)
### 1. Story Structure Format (Template Compliance)
**Check:** Story description follows template structure
⚠️ **Important:** Request FULL Story description from Linear (not truncated) to validate all 8 sections.
**Required Sections (in order):**
1. **Story** (As a / I want / So that)
2. **Context** (Current Situation + Desired Outcome)
3. **Acceptance Criteria** (Given-When-Then: Main Scenarios + Edge Cases + Error Handling)
4. **Implementation Tasks** (List with links including final test task)
5. **Test Strategy** (Unit 70% / Integration 20% / E2E 10%)
6. **Technical Notes** (Architecture Considerations + Integration Points + Performance & Security)
7. **Definition of Done** (Functionality + Testing + Code Quality)
8. **Dependencies** (Depends On + Blocks)
✅ All 8 sections present in correct order
✅ Each section has non-empty content
✅ Required subsections present (Context: Current Situation/Desired Outcome)
❌ Missing sections → Add with template placeholders
❌ Sections out of order → Reorder to match template
❌ Empty sections → Add placeholder text
**Fix Actions:**
When structure violations detected:
1. Parse current Story description
2. Identify missing/misplaced sections
3. Restructure:
- Add missing sections with placeholders (_TODO: Fill this section_)
- Reorder sections to match template
- Add missing subsections (Current Situation, Desired Outcome, etc.)
4. Update Linear issue via `mcp__linear-server__update_issue`
5. Add comment to Linear explaining changes
**Template Reference:** `../../ln-220-story-coordinator/references/story_template_universal.md` (v5.0.0)
**Skip Fix When:**
- Story in Done/Canceled status
- Story older than 30 days (legacy, don't touch)
### 2. Tasks Structure Format (Template Compliance - EVERY Task)
**Check:** All child Task descriptions follow template structure
**Equally Critical:** This check is as important as Story validation (#1). EVERY Task must comply with task_template_universal.md.
⚠️ **Important:** Request FULL Task description from Linear (not truncated) for EACH Task to validate all 7 sections.
**Required Sections (in order for EACH Task):**
1. **Context** (Current State + Desired State)
2. **Implementation Plan** (Phase 1-3 with checkboxes)
3. **Technical Approach** (Recommended + Why + Patterns + Alternatives)
4. **Acceptance Criteria** (Given-When-Then with checkboxes)
5. **Affected Components** (Implementation + Documentation)
6. **Existing Code Impact** (Refactoring + Tests to Update + Documentation to Update)
7. **Definition of Done** (Checklist)
> [!NOTE]
> Test Strategy removed from Tasks - all tests in Story's final task
✅ All 7 sections present in correct order in EVERY Task
✅ Each section has non-empty content in every Task
✅ Required subsections present in every Task
❌ Missing sections in any Task → Add with template placeholders
❌ Sections out of order in any Task → Reorder to match template
**Fix Actions:**
For each Task with structure violations:
1. Parse Task description
2. Identify missing/misplaced sections
3. Restructure each Task
4. Update Linear issue for each Task via `mcp__linear-server__update_issue`
5. Add comment to Linear for each fixed Task
**Template Reference:** `../../ln-311-task-creator/references/task_template_implementation.md` (v5.0.0)
**Skip Fix When:**
- Task in Done/Canceled status
- Task older than 30 days (legacy, don't touch)
### 3. Story Statement
**Check:** Clear, specific, user-focused (As a / I want / So that)
✅ "As a API client, I want to authenticate with OAuth2 tokens, So that users can securely access their data"
❌ "Improve authentication" (vague, no user context)
### 4. Acceptance Criteria (Story Level)
**Check:** Specific, testable, Given/When/Then format covering Story goal
✅ "Given valid OAuth2 token, When API request sent, Then user authenticated and data returned"
✅ "Given invalid token, When API request sent, Then 401 error returned"
❌ "Authentication should work correctly" (not testable)
### 5. Technical Approach (Story Level)
**Check:** Follows project architecture patterns, not over-engineered, consistent with previous Story
✅ "Use OAuth2 library (authlib 1.3+) for token validation, integrate with existing User model"
❌ "Implement custom JWT parser and validation" (library exists, YAGNI violation)
**Questions:**
- Does standard library solve Story goal?
- Is there simpler architectural approach? (KISS)
- Does Story duplicate existing functionality? (DRY)
- Which guide covers this architectural pattern?
- Are all layers properly involved? (API → Service → Repository)
**If previous Story context loaded (Phase 2 step 7):**
- ✅ Current Story uses same guides as previous Story (consistency)
- ✅ Current Story reuses components from previous Story (no reinvention)
- ✅ Current Story integrations compatible with previous Story
- ❌ Current Story creates duplicate component that exists in previous Story → Add TODO
- ❌ Current Story conflicts with previous Story integrations → Add TODO
**Auto-fix actions:**
- Add missing guides from previous Story to Technical Notes
- Add TODO if duplicate components detected
- Add TODO if conflicting integrations detected
- Add context reference: "Related to previous Story [US00X]"
### 6. Library & Version Research (Story Level)
**Check:** Story Technical Notes contain Library Research table populated by ln-220-story-coordinator Phase 3
✅ Library Research subsection present in Technical Notes
✅ Library Research table filled with: Library name, Version (v[X.Y.Z]), Purpose, Docs URL
✅ Key APIs listed (2-5 method signatures with purpose)
✅ Key constraints documented (async support, memory limitations, multi-process caveats, compatibility)
✅ Standards compliance documented (RFC/spec references if applicable, e.g., "RFC 6749 OAuth 2.0")
✅ Latest stable versions specified (prefer LTS, avoid alpha/beta/RC)
✅ Tasks reference library specs from Story (not duplicating research)
❌ Library Research subsection missing → **Auto-fix:** Research via MCP Context7 + Ref, populate table, update Story in Linear
❌ Library Research table empty or incomplete → **Auto-fix:** Research and fill missing fields
❌ Outdated library versions (> 6 months old stable release) → **Auto-fix:** Update to current stable via MCP Context7
❌ Missing Key APIs → **Auto-fix:** Research via MCP Context7 and add 2-5 key methods
❌ Missing constraints/limitations → **Auto-fix:** Research via MCP Ref and add known issues
❌ Bleeding edge versions (alpha/beta/RC) when stable exists → **Auto-fix:** Downgrade to latest stable
❌ Tasks implement custom helpers when library provides built-in methods → **Auto-fix:** Update Task Technical Approach to use library methods
❌ No guide for external package in `docs/guides/` → **Flag for guide creation** (handled by Phase 3)
**NOTE:** Library research should be performed in ln-220-story-coordinator Phase 3. This check validates it happened and updates if needed. If Library Research subsection is completely missing, it indicates Phase 3 was skipped (rare case).
**Auto-fix actions (#6):**
1. **If Library Research table missing:**
- Research via `mcp__context7__resolve-library-id()` + `mcp__context7__get-library-docs()`
- Research via `mcp__Ref__ref_search_documentation()` for best practices and standards
- Populate full table (libraries, versions, purpose, docs, key APIs, constraints, standards)
- Update Story description in Linear via `mcp__linear-server__update_issue()`
- Add comment in Linear: "Library research added (Phase 3 was skipped initially)"
2. **If versions outdated:**
- Research latest stable via MCP Context7
- Update version numbers in table
- Update Story description in Linear
- Add comment: "Library versions updated to 2025 standards"
3. **If Key APIs or constraints missing:**
- Research via MCP Context7 (library docs) + MCP Ref (best practices)
- Add missing sections to table
- Update Story description in Linear
- Add comment: "Library technical details completed"
**Tools:**
- MCP Context7: `mcp__context7__resolve-library-id()`, `mcp__context7__get-library-docs()`
- MCP Ref: `mcp__Ref__ref_search_documentation()`
- WebSearch (fallback if library not in Context7/Ref)
- Linear: `mcp__linear-server__update_issue()` for Story updates
### 7. Tests Integration (Story Level)
**Check:** Story has Test Strategy section, final Task dedicated to tests
✅ Story has Test Strategy section (Risk-Based Testing: 2-5 E2E, 3-8 Integration, 5-15 Unit, 10-28 total, Priority ≥15) focusing on business logic (not frameworks/libraries/trivial getters)
✅ Final Task in Implementation Tasks list is test task
✅ Story DoD includes: "All tests passing (Unit/Integration/E2E)"
✅ Test Strategy specifies E2E type (API or UI based on application)
✅ No duplicate test coverage - Each behavior tested once at appropriate level
❌ Story missing Test Strategy section
❌ No final test task planned
❌ Implementation Tasks include test sections (should be test-free)
### 8. Documentation Integration (Story + Tasks Level)
**Check:** Docs integrated across Story Tasks, not separate
✅ Story DoD includes: "Documentation updated"
✅ Tasks include doc updates in Affected Components
❌ Separate Task: "Document Story implementation" (creates stale docs)
❌ Story without documentation plan in Tasks
### 9. Story Size
**Check:** Reasonable scope (3-8 Tasks, ~1-2 weeks) AND each task is optimal size (3-5 hours)
**Story-level check:**
✅ 4-6 Tasks covering API → Service → Repository → Tests
❌ Too large: "Implement complete auth + authorization + audit" → Split into multiple Stories
❌ Too small: Single trivial change → Combine or make it a standalone Task
**Task-level check (granularity):**
✅ Each task 3-5 hours development time (atomic, testable unit)
✅ Task: "Implement token validation middleware" (~4 hours: logic + error handling + integration)
❌ Too granular (< 3h): "Add import statement", "Create empty function" → Combine with related work
❌ Too large (> 8h): "Implement complete OAuth2 flow" → Decompose into smaller tasks (generation + validation + refresh + revocation)
**Red flags:**
- Tasks with overly detailed decomposition (< 3h each) - sign of over-planning
- Tasks with vague scope (> 8h estimated) - needs further breakdown
### 10. YAGNI Compliance (Story Level)
**Check:** Story delivers only what is needed NOW
✅ "OAuth2 token authentication" (current requirement)
❌ "Add multi-factor authentication" (not in current requirements)
❌ "Support 5 OAuth providers" (only 1 provider needed now)
### 11. KISS Compliance (Story Level)
**Check:** Simplest architectural solution that delivers Story goal
✅ "Use existing OAuth2 library with standard flow" (simple, proven)
❌ "Implement distributed auth microservice with event sourcing" (over-engineered for auth)
### 12. Guide References (Story Level)
**Check:** Story Technical Notes reference existing guides or propose new
✅ "Follow [Guide 05: Authentication Pattern](link) for OAuth2 flow"
✅ "Create new guide: Multi-Tenant Authentication Strategy"
❌ No guide references in Story Technical Notes (architectural pattern not documented)
### 13. Foundation-First Execution Order (Story Level)
**Check:** Story implements foundation before consumers (for testability)
✅ Task order: 1. Token Repository (database) → 2. Auth Service → 3. API endpoint (consumer)
✅ Each layer is testable when built (no mocks needed for lower layers)
❌ Task order: 1. API endpoint → 2. Auth Service → 3. Token Repository (can't test without DB)
**Detection Keywords:**
- Database/Foundation: repository, database, schema, migration, entity
- Service: service, business logic, use case
- Consumer: endpoint, route, controller, API, UI component
**Exceptions:** Foundation layer, standard infrastructure, generic utilities
### 14. Code Quality Fundamentals (Story Level)
**Check:** Story Tasks avoid hardcoded values and use proper configuration management
✅ "Store API timeout in config: `config.api.timeout = 5000`" (configurable)
✅ "Use environment variable: `const maxRetries = process.env.MAX_RETRY_COUNT || 3`"
✅ "Named constant with explanation: `const BUFFER_SIZE = 1024 // Optimal for 4KB page size`"
❌ "Set timeout to 5000ms in code" (magic number without explanation)
❌ "`const API_URL = 'https://api.example.com'`" (hardcoded URL, should be env var)
❌ "`const MAX_ITEMS = 100`" (magic number without WHY explanation)
**Must check:**
- Magic numbers extracted to named constants or configuration
- Hardcoded paths/URLs moved to config files or environment variables
- API keys and credentials use environment variables (never in code)
- Timeouts, limits, thresholds are configurable
- Named constants have explanatory comments (WHY this value)
> [!NOTE]
> This check is performed at Story level (review Technical Notes and Implementation Tasks descriptions), not code inspection.
### 15. Industry Standards Compliance (Story Level)
**Check:** Story solution follows industry standards and RFCs (checked BEFORE applying KISS/YAGNI)
**Hierarchy:** Industry Standards (Level 1) > Security Standards (Level 2) > KISS/YAGNI/DRY (Level 3)
✅ "Implement POST /auth/token with grant_type parameter per OAuth 2.0 RFC 6749" (standard-compliant)
✅ "Use OpenAPI 3.1 spec for API documentation" (follows industry standard)
✅ "REST API follows RESTful principles (resource-based URLs, proper HTTP methods)" (standard design)
✅ "WebSocket handshake per RFC 6455" (protocol compliance)
❌ "Create separate /tokens and /refresh endpoints for simplicity" (non-standard OAuth flow, KISS conflicts with RFC 6749)
❌ "Custom authentication flow instead of OAuth 2.0" (reinventing standard, integration issues)
❌ "Non-RESTful API design (e.g., GET /api/deleteUser)" (violates REST principles)
**Common standards to check (examples - not exhaustive):**
- **OAuth 2.0:** RFC 6749 compliance (unified /token endpoint, grant_type parameter, standard flows)
- **REST API:** RESTful principles (resource-based URLs, proper HTTP methods, status codes)
- **OpenAPI:** API documentation follows OpenAPI 3.x specification
- **Protocols:** HTTP/HTTPS, WebSocket, GraphQL standards compliance
- **Data formats:** JSON (RFC 8259), XML, YAML standard compliance
---
### Evidence-Based Verification (MANDATORY)
**Trigger conditions (when this criterion applies):**
- Story involves protocols, APIs, authentication, data formats
- Story references external integrations or library usage
- Task implementation path not documented in existing guides/manuals
**REQUIRED actions (cannot mark ✅ without evidence):**
1. **Check existing documentation FIRST:**
- Scan `docs/guides/` for relevant implementation patterns
- Scan `docs/manuals/` for library/API references
- Scan `docs/adrs/` for architectural decisions
2. **IF documentation gap found → MUST invoke workers:**
- Missing pattern guide → MUST invoke `ln-321-guide-creator`
- Missing library manual → MUST invoke `ln-323-manual-creator`
- Missing architectural decision → MUST invoke `ln-322-adr-creator`
- Workers perform research via MCP Ref/Context7 internally
3. **Document compliance (REQUIRED evidence):**
- Document path (existing or created): `docs/guides/XX-pattern.md`
- OR Worker invocation result: "Created via ln-321-guide-creator"
- OR Explicit skip reason: "No applicable standards - Story is internal refactoring only"
4. **IF no applicable standards:**
- MUST explicitly state reason in Verification Log
- CANNOT leave blank or assume "not applicable"
**Self-Audit Question (MUST answer before marking ✅):**
> "Did I verify implementation path via docs/worker? Evidence: ___"
If answer is blank or generic → CANNOT mark ✅ → MUST perform verification first
---
**Red Flags:**
❌ Custom implementation when industry standard exists (OAuth, REST, OpenAPI)
❌ Non-standard endpoints/flows for "simplicity" (KISS overriding RFC compliance)
❌ "Proprietary" protocols when standard protocol available
❌ Non-compliant API design (e.g., mixing REST and RPC styles)
❌ **Marking ✅ without documented evidence** (fake verification)
**Auto-fix actions (#15):**
- Check existing docs in `docs/guides/`, `docs/manuals/`, `docs/adrs/`
- IF gap found → Invoke ln-321/ln-322/ln-323 workers (they perform research internally)
- Add document links to Story Technical Notes
- Update Tasks with standard-compliant implementation
- Add RFC/spec references in Technical Notes
- Update Linear issues
- Add comment: "Standards verified via [document path] OR created via [worker name]"
**Verification Log:** Document evidence in `checkpoints/{STORY_ID}_verification_log.md`
---
## Quick Verification Matrix
| Criterion | Pass | Notes | Evidence Required |
|-----------|------|-------|-------------------|
| Story follows template? | ☐ | 8 sections in order | Section list |
| All Tasks follow template? | ☐ | 7 sections each | Task validation count |
| Clear Story statement? | ☐ | As a/I want/So that | Quote statement |
| Testable AC? | ☐ | Given/When/Then at Story level | AC count |
| Test Strategy present? | ☐ | Risk-Based Testing (2-5 E2E, 3-8 Int, 5-15 Unit) | Test counts |
| Final test task planned? | ☐ | Last task in Implementation Tasks | Task list |
| **Standards compliant?** | ☐ | **OAuth 2.0, REST, RFCs - checked FIRST** | **Doc path OR worker call** |
| Follows patterns? | ☐ | References guides in Technical Notes | Guide links |
| Library research? | ☐ | Latest versions, no reinventing | Version list |
| Docs integrated? | ☐ | Story DoD + Tasks include docs | Integration proof |
| Size 3-8 Tasks? | ☐ | Not too small/large | Task count |
| YAGNI? | ☐ | No premature features | Scope review |
| KISS? | ☐ | Simplest solution (within standards) | Simplicity reason |
| Guides referenced? | ☐ | Links to patterns | Guide paths |
| Foundation-first? | ☐ | Task order: DB→Repo→Service→API | Task order |
| No hardcoded values? | ☐ | Config management, no magic numbers | TODO placeholders |
---
## Evidence-Based Verification Protocol
**MANDATORY:** Before marking ANY criterion as ✅, agent MUST:
1. **Answer Self-Audit Question** for that criterion (not blank)
2. **Provide concrete evidence** (document path, tool result, or explicit reason)
3. **Document in Verification Log:** `checkpoints/{STORY_ID}_verification_log.md`
**If evidence missing → CANNOT mark ✅ → MUST perform required action first**
**Template:** `verification_log_template.md`
---
**Result:** ALL criteria auto-fixed → ALWAYS Approve → Todo
> [!NOTE]
> No "Keep in Backlog" path exists - all issues auto-fixed before approval
> [!WARNING]
> Marking ✅ without documented evidence = INVALID verification
**Hierarchy:** Industry Standards (#15) checked BEFORE KISS/YAGNI (#11/#10)
---
## Common Issues & Auto-Fix Actions
**All issues are AUTO-FIXED automatically. No manual intervention required.**
1. **Incorrect Story Structure** - Missing/misplaced sections
- **Auto-fix:** Restructure Story per template, add missing sections with placeholders, reorder sections, update Linear
2. **Incorrect Task Structure** - Missing/misplaced sections in Tasks
- **Auto-fix:** Restructure each Task per template, add missing sections with placeholders, update Linear for each Task
3. **Vague Story** - "Improve X" instead of As a/I want/So that
- **Auto-fix:** Extract persona from Context, identify capability from Technical Notes, rewrite Story statement, update Linear
4. **Non-Testable AC** - Vague acceptance criteria
- **Auto-fix:** Convert to Given/When/Then format, add edge cases from Context, ensure 3-5 AC, update Linear
5. **Outdated Solution** - Not using 2025 best practices
- **Auto-fix:** Rewrite Story Technical Notes with modern approach, update Tasks with optimized plan, update Linear
6. **Outdated Libraries** - Old package versions
- **Auto-fix:** Replace with current stable versions, update Story Technical Notes and Tasks, update Linear
7. **Missing Test Strategy** - No Risk-Based Testing section
- **Auto-fix:** Add Test Strategy section (2-5 E2E, 3-8 Integration, 5-15 Unit, 10-28 total, Priority ≥15), update Story DoD, update Linear
8. **Standalone Doc Task** - Separate documentation task
- **Auto-fix:** Remove doc task, integrate docs into Affected Components of implementation tasks, update Linear
9. **Wrong Story/Task Size** - Too large (> 8 tasks) or too small (< 3 tasks), wrong task granularity (> 8h or < 3h)
- **Auto-fix:** Add TODO placeholders flagging size issues for user review, update Linear
10. **YAGNI Violations** - Premature features in scope
- **Auto-fix:** Move to Story "Out of Scope" or "Future Enhancements", remove from Tasks, update Linear
11. **KISS Violations** - Over-engineered solution
- **Auto-fix:** Simplify architectural approach in Technical Notes, update Tasks with simplified implementation, update Linear
12. **Missing Guide Links** - No guides referenced
- **Auto-fix:** Insert auto-created and existing guide links in Story Technical Notes "Related Guides:" subsection, update Linear
13. **Provider-First Tasks** - Wrong task order
- **Auto-fix:** Reorder Tasks (Consumer → Service → Provider), update Story Implementation Tasks section, update Linear
14. **Hardcoded Values** - Magic numbers, hardcoded URLs/paths, credentials in code
- **Auto-fix:** Add TODO placeholders for extracting magic numbers, moving URLs to config, using env vars for credentials, update Linear
15. **Non-standard Implementations** - Custom solutions when industry standards exist (OAuth, REST, RFCs)
- **Auto-fix:** Research RFC/standard via MCP Ref, rewrite Story Technical Notes to comply with standard, update Tasks with standard-compliant implementation, add RFC/spec references, update Linear, add comment with standard name and RFC/spec number
---
## Post-Verification (Always Approve)
**Result:** ALWAYS Approve → Todo (after ALL auto-fixes applied)
- Story: Backlog → Todo
- All child Tasks: Backlog → Todo
- kanban_board.md: Updated
- Optional warning comment if TODO placeholders exist (user review needed but don't block execution)
---
**Version:** 7.0.0 (Added Evidence-Based Verification Protocol, Self-Audit Questions, Verification Log requirement)
**Last Updated:** 2025-11-23

43
skills/ln-321-guide-creator/SKILL.md Normal file
View File

@@ -0,0 +1,43 @@
---
name: ln-321-guide-creator
description: Creates minimal guides (6 sections, ~300-500 words) for reusable patterns. Auto-research via MCP Ref/Context7. Returns guide path for linking.
---
# Guide Creator
Produces pattern guides with sources and patterns table when a new reusable approach is found.
## Purpose & Scope
- Auto-research best practices for a named pattern; cite versions/dates.
- Generate 6-section guide: SCOPE tags, Principle, Our Implementation, Patterns table (Do/Don't/When), Sources, Related + Last Updated.
- Validate against documentation standards; save to `docs/reference/guides/NN-pattern.md`; return path.
## When to Use
- Pattern is missing in `docs/reference/guides/` or Task/Story Technical Notes reference an undocumented pattern.
- Need a concise “how to implement” reference (not ADR/decision, not API manual).
## Workflow (concise)
1) **Research:** MCP Ref + Context7 for official docs and framework usage; extract principle, 2-3 do/don'ts, versions/dates.
2) **Generate:** Fill 6 sections with patterns table; no code snippets; 300-500 words; language per Story/Task.
3) **Validate:** Ensure SCOPE tags, sources dated, patterns table, no ADR-style rationale, POSIX ending, maintenance/Last Updated; auto-fix standards if needed.
4) **Save:** Confirm, write `docs/reference/guides/NN-pattern-name.md` (NN = next number), optionally update `docs/reference/README.md` if placeholder exists; return path.
## Critical Rules
- Cite official sources with versions/dates (>=2025 or version-specific).
- No code snippets or ADR rationale; keep neutral instructional tone.
- One pattern per guide; include Do/Don't/When table.
- Preserve language (EN/RU) from request.
## Definition of Done
- Research done (Ref + Context7) with principle and sources extracted.
- Guide generated with all 6 sections and patterns table; no placeholders.
- Standards check passed/auto-fixed (SCOPE, maintenance, POSIX).
- Saved to guides with correct numbering; path returned; README updated if placeholder present.
## Reference Files
- Template/reference: `ln-321-guide-creator/references/guide_template.md`
- Standards (if present): `docs/DOCUMENTATION_STANDARDS.md`
---
Version: 6.0.0 (Condensed flow and rules)
Last Updated: 2025-11-26

60
skills/ln-321-guide-creator/diagram.html Normal file
View File

@@ -0,0 +1,60 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>ln-321-guide-creator - State Diagram</title>
<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
<link rel="stylesheet" href="../shared/css/diagram.css">
</head>
<body>
<div class="container">
<header>
<h1>📚 ln-321-guide-creator</h1>
<p class="subtitle">Guide Creator - State Diagram</p>
</header>
<div class="info-box">
<h3>📋 Overview</h3>
<ul>
<li><strong>Purpose:</strong> Research and create minimal project guides (6 sections, 300-500 words)</li>
<li><strong>AUTO-RESEARCH:</strong> Automated via MCP Ref + Context7 (NO manual questions)</li>
<li><strong>Output:</strong> Returns guide path for linking in Story Technical Notes</li>
</ul>
</div>
<div class="diagram-container">
<div class="mermaid">
graph TD
Start([Start: Create Guide]) --> Phase0[Phase 0: Research & Discovery<br/>AUTO-RESEARCH automated]
subgraph Research [Automated Research]
R1[Search library docs<br/>MCP Ref + Context7]
R1 --> R2[Search framework patterns<br/>Best practices]
R2 --> R3[Analyze findings<br/>Extract principle]
end
Phase0 --> R1
R3 --> Phase1
Phase1[Phase 1: Pattern Analysis]
Phase1 --> Phase2[Phase 2: Generation<br/>6 sections 300-500 words<br/>NO ADR concepts]
Phase2 --> Phase3[Phase 3: Confirmation<br/>Save to docs/guides/<br/>Return path]
Phase3 --> UserConfirm{Confirm?}
UserConfirm -->|Yes| Save[Save guide file]
UserConfirm -->|No| Phase2
Save --> End([End])
classDef discovery fill:#E3F2FD,stroke:#1976D2,stroke-width:2px
classDef processing fill:#FFF9C4,stroke:#F57C00,stroke-width:2px
classDef decision fill:#FFE0B2,stroke:#E64A19,stroke-width:2px
classDef action fill:#C8E6C9,stroke:#388E3C,stroke-width:2px
class Phase0,R1,R2,R3 discovery
class Phase1,Phase2 processing
class UserConfirm decision
class Phase3,Save action
</div>
</div>
<footer>
<p>ln-321-guide-creator | AUTO-RESEARCH: MCP Ref + Context7 + WebSearch | NO ADR concepts</p>
</footer>
</div>
<script>
mermaid.initialize({ startOnLoad: true, theme: 'default', flowchart: { useMaxWidth: true, htmlLabels: true, curve: 'basis' } });
</script>
</body>
</html>

43
skills/ln-321-guide-creator/references/guide_template.md Normal file
View File

@@ -0,0 +1,43 @@
# [Pattern Name]
<!-- SCOPE: Pattern documentation ONLY. Contains principle (industry standard), implementation (project-specific), code structure patterns (DO/DON'T), sources. -->
<!-- DO NOT add here: Architectural decisions → ADR, Implementation code → Task descriptions, Multiple patterns → Separate guides, Requirements → Requirements.md, API specs → api_spec.md -->
## Principle
{{PRINCIPLE}}
(1-2 sentences describing the core industry best practice with version/date citation)
## Our Implementation
{{OUR_IMPLEMENTATION}}
(1 paragraph: how we apply this pattern in our project context, which layers/components affected, key integration points)
## Patterns
| Do This ✅ | Don't Do This ❌ | When to Use |
|-----------|------------------|-------------|
| {{PATTERN_1_DO}} | {{PATTERN_1_DONT}} | {{PATTERN_1_WHEN}} |
| {{PATTERN_2_DO}} | {{PATTERN_2_DONT}} | {{PATTERN_2_WHEN}} |
| {{PATTERN_3_DO}} | {{PATTERN_3_DONT}} | {{PATTERN_3_WHEN}} |
## Sources
- {{SOURCE_1}}
- {{SOURCE_2}}
- Internal: [Architecture.md](../project/architecture.md)
## Related
**ADRs:** {{RELATED_ADRS}}
**Guides:** {{RELATED_GUIDES}}
---
**Last Updated:** {{DATE}}
---
**Guide Template Version:** 4.0.0 (Minimal Format)
**Template Last Updated:** 2025-01-31

45
skills/ln-322-adr-creator/SKILL.md Normal file
View File

@@ -0,0 +1,45 @@
---
name: ln-322-adr-creator
description: Creates ADRs (Nygard format, 7 sections, ~300-500 words) via short Q&A. Assigns next ADR number and validates standards.
---
# ADR Creator
Captures a single architecture decision with minimal dialog and saves it to the ADR collection.
## Purpose & Scope
- Assign next ADR number in `docs/reference/adrs/`.
- Gather title/category/context/decision/rationale/alternatives/consequences/status via 5 questions.
- Generate ADR file from template; validate standards; return path.
## When to Use
- Need to document a specific architectural/technical decision (one per ADR).
- Project already has reference docs structure (`docs/reference/adrs/`).
- Not for broad docs creation (use ln-110/ln-114 for initial structures).
## Workflow (concise)
1) **Detect number:** Scan existing ADR files, pick next zero-padded number, build slug.
2) **Dialog (5 Qs):** Title; category (Strategic/Technical); Context; Decision + Rationale; Alternatives table (2 rows); Consequences + Related + Status.
3) **Generate:** Copy template, fill placeholders (title/date/status/category/decision makers/context/decision/rationale/alternatives/consequences/related).
4) **Validate:** Ensure SCOPE tags, maintenance/Last Updated, POSIX ending; apply DOCUMENTATION_STANDARDS if present; auto-fix missing bits.
5) **Save & link:** Write `docs/reference/adrs/adr-NNN-slug.md`; optionally update `docs/reference/README.md` if placeholder found; report path and next steps.
## Critical Rules
- One decision per ADR; English language per standard.
- Include 2 alternatives with pros/cons/rejection; keep within ~300-500 words.
- Do not create if `docs/reference/adrs/` missing (warn instead).
- Preserve zero-padded numbering; no gaps.
## Definition of Done
- Next ADR number/slug determined; placeholders filled; no leftovers.
- File saved in adrs/ with ISO date, status, category, consequences, alternatives table.
- Standards validated (SCOPE, maintenance, POSIX); README updated if placeholder present.
- Path returned and user reminded to reference in architecture.md if needed.
## Reference Files
- Template: `ln-322-adr-creator/references/adr_template.md`
- Standards: `docs/DOCUMENTATION_STANDARDS.md` (if exists)
---
Version: 7.0.0 (Condensed ADR creation and standards validation)
Last Updated: 2025-11-26

105
skills/ln-322-adr-creator/diagram.html Normal file
View File

@@ -0,0 +1,105 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>ln-322-adr-creator - State Diagram</title>
<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
<link rel="stylesheet" href="../shared/css/diagram.css">
</head>
<body>
<div class="container">
<header>
<h1>📝 ln-322-adr-creator</h1>
<p class="subtitle">Architecture Decision Record Creator - State Diagram</p>
</header>
<div class="info-box">
<h3>📋 Workflow Overview</h3>
<ul>
<li><strong>Purpose:</strong> Create minimal Architecture Decision Records (ADRs) through 5-question dialog</li>
<li><strong>Format:</strong> Nygard format with 7 sections (~300-500 words)</li>
<li><strong>Categories:</strong> Strategic (business, patterns) or Technical (frameworks, infra)</li>
<li><strong>Use after:</strong> ln-111-docs-creator creates project structure</li>
</ul>
</div>
<div class="legend">
<div class="legend-item">
<div class="legend-color color-discovery"></div>
<span>ADR Discovery</span>
</div>
<div class="legend-item">
<div class="legend-color color-dialog"></div>
<span>Dialog/Generation</span>
</div>
<div class="legend-item">
<div class="legend-color color-decision"></div>
<span>Decision Point</span>
</div>
<div class="legend-item">
<div class="legend-color color-action"></div>
<span>Update/Summary</span>
</div>
</div>
<div class="diagram-container">
<div class="mermaid">
graph TD
Start([Start: Create ADR]) --> Phase1[Phase 1: ADR Number Detection<br/>Glob existing ADRs<br/>Calculate next number]
Phase1 --> Phase2[Phase 2: Interactive Dialog<br/>5 questions:<br/>Q1: Decision title<br/>Q2: Category Strategic/Technical<br/>Q3: Context<br/>Q4: Considered options<br/>Q5: Decision + consequences]
Phase2 --> Phase3[Phase 3: Generate ADR<br/>7 sections Nygard format<br/>300-500 words]
Phase3 --> ReadmeExists{README.md<br/>exists?}
ReadmeExists -->|Yes| Phase4[Phase 4: Update Documentation Hub<br/>Add ADR link to README]
ReadmeExists -->|No| Phase5
Phase4 --> Phase5
Phase5[Phase 5: Summary<br/>Display ADR path + next steps]
Phase5 --> End([End])
%% Styling
classDef discovery fill:#E3F2FD,stroke:#1976D2,stroke-width:2px
classDef dialog fill:#FFF9C4,stroke:#F57C00,stroke-width:2px
classDef decision fill:#FFE0B2,stroke:#E64A19,stroke-width:2px
classDef action fill:#C8E6C9,stroke:#388E3C,stroke-width:2px
class Phase1 discovery
class Phase2,Phase3 dialog
class ReadmeExists decision
class Phase4,Phase5 action
</div>
</div>
<div class="info-box">
<h3>🔑 Key Features</h3>
<ul>
<li><strong>5 Questions:</strong> Title, Category, Context, Options, Decision</li>
<li><strong>Minimal Format:</strong> 300-500 words, 7 sections (Nygard format)</li>
<li><strong>Categorization:</strong> Strategic (business decisions, patterns) vs Technical (frameworks, infrastructure)</li>
<li><strong>Auto-numbering:</strong> Automatically detects next ADR number</li>
</ul>
</div>
<footer>
<p>Generated for ln-322-adr-creator skill | Version 3.0.0</p>
<p>Diagram format: Mermaid.js | Last updated: 2025-11-08</p>
</footer>
</div>
<script>
mermaid.initialize({
startOnLoad: true,
theme: 'default',
flowchart: {
useMaxWidth: true,
htmlLabels: true,
curve: 'basis'
}
});
</script>
</body>
</html>

70
skills/ln-322-adr-creator/references/adr_template.md Normal file
View File

@@ -0,0 +1,70 @@
# ADR-{{NUMBER}}: {{TITLE}}
**Date:** {{DATE}} | **Status:** {{STATUS}} | **Category:** {{CATEGORY}} | **Decision Makers:** {{DECISION_MAKERS}}
<!-- SCOPE: Architecture Decision Record for ONE specific technical decision ONLY. Contains context, decision, rationale, consequences, alternatives (2 with pros/cons). -->
<!-- DO NOT add here: Implementation code → Task descriptions, Requirements → Requirements.md, Multiple decisions → Create separate ADRs, Architecture diagrams → Architecture.md -->
---
## Context
{{CONTEXT}}
(2-3 sentences: background, problem, constraints, forces driving this decision)
---
## Decision
{{DECISION}}
(1-2 sentences: clear statement of what we decided, including version/constraints if applicable)
---
## Rationale
{{RATIONALE}}
(2-3 key reasons WHY we chose this solution)
---
## Consequences
**Positive:**
{{POSITIVE_CONSEQUENCES}}
(2-4 bullets: benefits, advantages)
**Negative:**
{{NEGATIVE_CONSEQUENCES}}
(2-4 bullets: trade-offs, costs, technical debt)
---
## Alternatives Considered
| Alternative | Pros | Cons | Why Rejected |
|-------------|------|------|--------------|
| {{ALT_1_NAME}} | {{ALT_1_PROS}} | {{ALT_1_CONS}} | {{ALT_1_REJECTION}} |
| {{ALT_2_NAME}} | {{ALT_2_PROS}} | {{ALT_2_CONS}} | {{ALT_2_REJECTION}} |
---
## Related Decisions
{{RELATED_DECISIONS}}
(Optional: ADR-001, ADR-003)
---
**Last Updated:** {{DATE}}
---
**ADR Template Version:** 3.0.0 (With Categorization)
**Template Last Updated:** 2025-11-05

43
skills/ln-323-manual-creator/SKILL.md Normal file
View File

@@ -0,0 +1,43 @@
---
name: ln-323-manual-creator
description: Creates package/API manuals (300-500 words) with versioned methods/params/examples. Auto-research via MCP Ref/Context7. Returns manual path.
---
# Manual Creator
Generates neutral, version-specific API manuals for packages introduced in Stories/Tasks.
## Purpose & Scope
- Auto-research package version, methods, params, returns, exceptions, config, and official sources.
- Produce OpenAPI-inspired manual from template: Package info, Overview, Methods (signature/params/returns/example), Config, Limitations, Version notes, Related + Last Updated.
- Validate against documentation standards; save to `docs/reference/manuals/package-version.md`; return path.
## When to Use
- New package/library/API appears and lacks a manual.
- Need factual reference for implementation (not patterns/decisions).
## Workflow (concise)
1) **Research:** MCP Ref + Context7 for official docs/version; extract method signatures, params (type/required/default), returns, exceptions, examples, sources (dated/versioned).
2) **Generate:** Fill template sections; neutral tone; no how-to/opinions; include at least one example per method; language per request.
3) **Validate:** Ensure SCOPE tags, maintenance/Last Updated, POSIX ending; sources dated; defaults and required flags set; no placeholders; standards auto-fix if needed.
4) **Save:** Confirm; write `docs/reference/manuals/[package]-[version].md`; optionally update `docs/reference/README.md` if placeholder present; return path.
## Critical Rules
- Version-specific filenames; no numbering.
- Neutral/factual: no recommendations or rationale (that’s guides/ADRs).
- No how-to content; focus on APIs/methods/config.
- Preserve language (EN/RU) from request.
## Definition of Done
- Research captured (methods/params/examples/sources with versions/dates).
- Manual generated with all sections and examples; no placeholders.
- Standards check passed/auto-fixed (SCOPE, maintenance, POSIX).
- Saved to manuals/ with correct filename; path returned; README updated if placeholder present.
## Reference Files
- Template: `ln-323-manual-creator/references/manual_template.md`
- Standards: `docs/DOCUMENTATION_STANDARDS.md` (if exists)
---
Version: 3.0.0 (Condensed manual creation flow)
Last Updated: 2025-11-26

203
skills/ln-323-manual-creator/diagram.html Normal file
View File

@@ -0,0 +1,203 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>ln-323-manual-creator Workflow</title>
<link rel="stylesheet" href="../shared/css/diagram.css">
<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
<script>
mermaid.initialize({
startOnLoad: true,
theme: 'base',
themeVariables: {
primaryColor: '#4A90E2',
primaryTextColor: '#fff',
primaryBorderColor: '#2E5C8A',
lineColor: '#333',
secondaryColor: '#FDB45C',
tertiaryColor: '#F7464A',
background: '#ffffff',
mainBkg: '#4A90E2',
secondBkg: '#FDB45C',
tertiaryBkg: '#46BFBD',
textColor: '#333'
},
flowchart: {
useMaxWidth: true,
htmlLabels: true,
curve: 'basis'
}
});
</script>
</head>
<body>
<div class="container">
<header>
<h1>ln-323-manual-creator</h1>
<p class="subtitle">Package API Reference Manual Creation Workflow</p>
<p class="description">
Linear Workflow for creating minimal API reference manuals through automated research.
4 phases: Research (auto via MCP) → Analysis → Generation → Confirmation.
</p>
</header>
<div class="legend">
<h3>Color Coding</h3>
<div class="legend-grid">
<div class="legend-item">
<span class="legend-color discovery"></span>
<span>Discovery/Research (Phase 0)</span>
</div>
<div class="legend-item">
<span class="legend-color processing"></span>
<span>Processing (Phase 1-2)</span>
</div>
<div class="legend-item">
<span class="legend-color decision"></span>
<span>Decision (Phase 3)</span>
</div>
<div class="legend-item">
<span class="legend-color action"></span>
<span>Action (Save)</span>
</div>
</div>
</div>
<div class="mermaid">
graph TD
Start([Start: Package + Version]) --> Phase0[Phase 0: Research & Discovery<br/>AUTO 10-15 min]
Phase0 --> Context7[Context7: Library API Docs<br/>resolve-library-id + get-library-docs]
Phase0 --> MCPRef[MCP Ref: Official Docs<br/>API reference search]
Context7 --> Extract[Extract Method Signatures<br/>Parameters, Return Types]
MCPRef --> Extract
Extract --> Phase1[Phase 1: Method Analysis<br/>Parse signatures, Generate tables]
Phase1 --> ParseSig[Parse Method Signatures]
ParseSig --> ParamTable[Generate Parameter Tables<br/>name | type | required | default | description]
ParamTable --> Examples[Extract Usage Examples]
Examples --> Phase2[Phase 2: Manual Generation<br/>Copy template + Edit placeholders]
Phase2 --> CopyTemplate[Copy manual_template.md]
CopyTemplate --> Replace[Replace Placeholders<br/>PACKAGE, VERSION, METHODS]
Replace --> GenMethods[Generate Methods Sections<br/>For each method: signature + params + example]
GenMethods --> Validate{Validation<br/>SCOPE tags?<br/>Neutral tone?<br/>All params documented?}
Validate -->|Pass| Preview[Show Preview<br/>Package | Version | Methods | Length]
Validate -->|Fail| Fix[Fix Issues]
Fix --> Validate
Preview --> Phase3{Phase 3: User Confirmation<br/>Type 'confirm'?}
Phase3 -->|No| Preview
Phase3 -->|Yes| Save[Save Manual<br/>docs/manuals/package-version.md]
Save --> Return[Return File Path<br/>For linking in tasks/stories]
Return --> End([End])
classDef discovery fill:#4A90E2,stroke:#2E5C8A,color:#fff
classDef processing fill:#FDB45C,stroke:#E09A3E,color:#333
classDef decision fill:#F7931E,stroke:#C87016,color:#fff
classDef action fill:#46BFBD,stroke:#2E8B8B,color:#fff
class Phase0,Context7,MCPRef,Extract discovery
class Phase1,ParseSig,ParamTable,Examples,Phase2,CopyTemplate,Replace,GenMethods,Validate,Fix,Preview processing
class Phase3 decision
class Save,Return action
</div>
<div class="phases">
<h3>Workflow Phases</h3>
<div class="phase">
<h4>Phase 0: Research & Discovery (10-15 min, Automated)</h4>
<ul>
<li><strong>Context7:</strong> resolve-library-id("[package]") → get-library-docs(library_id, topic="methods")</li>
<li><strong>MCP Ref:</strong> "[package] v[version] API reference" search</li>
<li><strong>Extract:</strong> Method signatures, parameters, return types, exceptions, usage examples</li>
<li><strong>Output:</strong> Package metadata + method list + sources (2-3 official docs)</li>
</ul>
</div>
<div class="phase">
<h4>Phase 1: Method Analysis</h4>
<ul>
<li><strong>Parse Signatures:</strong> Method names, parameter lists, return types</li>
<li><strong>Generate Tables:</strong> Parameters table (name | type | required | default | description)</li>
<li><strong>Extract Examples:</strong> Representative usage examples from official docs</li>
</ul>
</div>
<div class="phase">
<h4>Phase 2: Manual Generation</h4>
<ul>
<li><strong>Copy Template:</strong> references/manual_template.md</li>
<li><strong>Replace Placeholders:</strong> {{PACKAGE_NAME}}, {{VERSION}}, {{METHODS}}, etc.</li>
<li><strong>Generate Methods Sections:</strong> For each method: signature + description + parameters table + returns + raises + example</li>
<li><strong>Validation:</strong> SCOPE tags, neutral tone, all params documented, official docs linked</li>
<li><strong>Show Preview:</strong> Package | Version | Methods count | Word count</li>
</ul>
</div>
<div class="phase">
<h4>Phase 3: Confirmation & Storage</h4>
<ul>
<li><strong>User Confirmation:</strong> Wait for "confirm" input</li>
<li><strong>Save Manual:</strong> docs/manuals/[package]-[version].md (NO sequential numbering)</li>
<li><strong>Return Path:</strong> File path for linking in tasks/stories</li>
</ul>
</div>
</div>
<div class="notes">
<h3>Key Characteristics</h3>
<ul>
<li><strong>AUTO-RESEARCH:</strong> Fully automated via MCP Context7 + Ref (no user questions)</li>
<li><strong>OpenAPI-inspired:</strong> Method signatures, parameters tables, neutral factual tone</li>
<li><strong>Version-specific:</strong> Filename format: package-version.md (e.g., httpx-0.24.0.md)</li>
<li><strong>Minimal format:</strong> 300-500 words, focus on methods we will use</li>
<li><strong>Integration:</strong> Auto-invoked by ln-320-story-validator when package+version detected</li>
</ul>
</div>
<div class="comparison">
<h3>When to Use</h3>
<table>
<thead>
<tr>
<th>Document Type</th>
<th>Focus</th>
<th>When to Create</th>
</tr>
</thead>
<tbody>
<tr>
<td><strong>Guide</strong> (ln-321-guide-creator)</td>
<td>HOW to implement (patterns, best practices)</td>
<td>Auto-invoked by ln-320-story-validator (ad-hoc)</td>
</tr>
<tr>
<td><strong>ADR</strong> (ln-322-adr-creator)</td>
<td>WHY we decided (alternatives, consequences)</td>
<td>Manual (during architecture phase, rare)</td>
</tr>
<tr class="highlight">
<td><strong>Manual</strong> (ln-323-manual-creator)</td>
<td>WHAT API can do (methods, parameters, examples)</td>
<td>Manual (after Story Done, optional)</td>
</tr>
</tbody>
</table>
</div>
<footer>
<p>Version: 1.0.0 | Last Updated: 2025-01-14</p>
<p>For more information, see <a href="SKILL.md">SKILL.md</a></p>
</footer>
</div>
</body>
</html>

119
skills/ln-323-manual-creator/references/manual_template.md Normal file
View File

@@ -0,0 +1,119 @@
# {{PACKAGE_NAME}} v{{VERSION}} - Usage Manual
<!-- SCOPE: API/Method reference ONLY. Contains technical descriptions, parameters, examples. -->
<!-- DO NOT add: How-to instructions → Guide, Decision rationale → ADR -->
## Package Information
**Package:** {{PACKAGE_NAME}}
**Version:** {{VERSION}}
**Installation:** `{{INSTALL_COMMAND}}`
**Documentation:** {{OFFICIAL_DOCS_URL}}
## Overview
{{PACKAGE_DESCRIPTION}}
## Methods We Use
---
### {{METHOD_1_NAME}}
**Signature:**
```{{LANGUAGE}}
{{METHOD_1_SIGNATURE}}
```
**Description:**
{{METHOD_1_DESCRIPTION}}
**Parameters:**
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| {{PARAM_1_NAME}} | {{PARAM_1_TYPE}} | {{PARAM_1_REQUIRED}} | {{PARAM_1_DEFAULT}} | {{PARAM_1_DESCRIPTION}} |
| {{PARAM_2_NAME}} | {{PARAM_2_TYPE}} | {{PARAM_2_REQUIRED}} | {{PARAM_2_DEFAULT}} | {{PARAM_2_DESCRIPTION}} |
**Returns:**
{{RETURN_TYPE}} - {{RETURN_DESCRIPTION}}
**Raises:**
* `{{EXCEPTION_1}}` - When {{EXCEPTION_1_CONDITION}}
* `{{EXCEPTION_2}}` - When {{EXCEPTION_2_CONDITION}}
**Example:**
```{{LANGUAGE}}
{{EXAMPLE_CODE}}
```
**Output:**
```
{{EXAMPLE_OUTPUT}}
```
{{METHOD_1_WARNINGS}}
---
### {{METHOD_2_NAME}}
**Signature:**
```{{LANGUAGE}}
{{METHOD_2_SIGNATURE}}
```
**Description:**
{{METHOD_2_DESCRIPTION}}
**Parameters:**
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| {{PARAM_1_NAME}} | {{PARAM_1_TYPE}} | {{PARAM_1_REQUIRED}} | {{PARAM_1_DEFAULT}} | {{PARAM_1_DESCRIPTION}} |
**Returns:**
{{RETURN_TYPE}} - {{RETURN_DESCRIPTION}}
**Raises:**
* `{{EXCEPTION_1}}` - When {{EXCEPTION_1_CONDITION}}
**Example:**
```{{LANGUAGE}}
{{EXAMPLE_CODE}}
```
---
## Configuration
{{CONFIGURATION_SECTION}}
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| {{CONFIG_1_NAME}} | {{CONFIG_1_TYPE}} | {{CONFIG_1_DEFAULT}} | {{CONFIG_1_DESCRIPTION}} |
| {{CONFIG_2_NAME}} | {{CONFIG_2_TYPE}} | {{CONFIG_2_DEFAULT}} | {{CONFIG_2_DESCRIPTION}} |
## Known Limitations
{{LIMITATIONS}}
* {{LIMITATION_1}}
* {{LIMITATION_2}}
## Version-Specific Notes
{{VERSION_NOTES}}
## Related Resources
* **Official Documentation:** {{OFFICIAL_DOCS_LINK}}
* **GitHub Repository:** {{GITHUB_URL}}
* **Related Guides:** {{RELATED_GUIDES}}
* **Related ADRs:** {{RELATED_ADRS}}
**Last Updated:** {{DATE}}

51
skills/ln-330-story-executor/SKILL.md Normal file
View File

@@ -0,0 +1,51 @@
---
name: ln-330-story-executor
description: Orchestrates Story tasks. Prioritizes To Review -> To Rework -> Todo, delegates to ln-331/ln-333/ln-334, hands Story quality to ln-340. Metadata-only loading up front.
---
# Story Execution Orchestrator
Executes a Story end-to-end by looping through its tasks in priority order and delegating quality gates to ln-340-story-quality-gate.
## Purpose & Scope
- Load Story + task metadata (no descriptions) and drive execution.
- Process tasks in order: To Review -> To Rework -> Todo (foundation-first order preserved from ln-310).
- Delegate per task type: ln-332-task-reviewer, ln-333-task-rework, ln-331-task-executor, ln-334-test-executor.
- Delegate Story quality to ln-340-story-quality-gate (Pass 1/Pass 2) and loop if new tasks are created.
## When to Use
- Story is Todo or In Progress and has implementation/refactor/test tasks to finish.
- Need automated orchestration through To Review and quality gates.
## Workflow (concise)
- **Phase 1 Discovery:** Auto-discover Team ID/config from kanban_board.md + CLAUDE.md.
- **Phase 2 Load:** Fetch Story metadata and all child task metadata via `list_issues(parentId=Story.id)` (ID/title/status/labels only). Summarize counts; do not call `get_issue` yet.
- **Phase 3 Loop (priority, review-after-each-task):**
1) To Review -> ln-332-task-reviewer (one task). Reload metadata after worker.
2) To Rework -> ln-333-task-rework (one task). After worker, verify status = To Review, then immediately call ln-332-task-reviewer on that same task. Reload metadata.
3) Todo -> pick first Todo; if label "tests" use ln-334-test-executor else ln-331-task-executor. After worker, verify status = To Review (not Done/In Progress), then immediately call ln-332-task-reviewer on that same task. Reload metadata. Repeat loop; never queue multiple tasks in To Review—review right after each execution/rework.
- **Phase 4 Quality Delegation:** Ensure all implementation tasks Done, then call ln-340-story-quality-gate Pass 1. If it creates tasks (test/refactor/fix), auto-validate (ln-320) and return to Phase 3. When test task is Done, set Story In Progress -> To Review and call ln-340 Pass 2. If Pass 2 fails and creates tasks, loop to Phase 3; if Pass 2 passes, Story goes To Review -> Done via ln-340.
## Critical Rules
- Metadata first: never load task descriptions in Phase 2; only workers load full text.
- Single-task operations: each worker handles only the passed task ID; ln-330 never bulk-updates tasks.
- Status discipline: after ln-331/ln-333/ln-334, task must be To Review; immediately invoke ln-332 on that task. Only ln-332 may set Done. Stop and report if any worker leaves task Done or In Progress.
- Source of truth: trust Linear metadata, not kanban_board.md, for orchestration decisions.
- Story status ownership: ln-330 moves Todo -> In Progress (first execution) and In Progress -> To Review (all tasks Done); ln-340 handles To Review -> Done.
## Definition of Done
- Story metadata and task metadata loaded via list_issues (no get_issue in Phase 2); counts shown.
- Loop executed: all To Review via ln-332; all To Rework via ln-333 then immediate ln-332 on the same task; all Todo via ln-331/ln-334 then immediate ln-332 on the same task (validated To Review after each worker).
- If tasks were created by ln-340: validated via ln-320 and executed through the loop.
- ln-340 Pass 1 invoked when impl tasks Done; Pass 2 invoked when test task Done or not needed. Result handled (pass/fail -> loop).
- Story status transitions applied (Todo -> In Progress -> To Review) and kanban updated by workers/ln-340.
- Final report with task counts and next step (if any).
## Reference Files
- Quality orchestration: `../ln-340-story-quality-gate/SKILL.md`
- Executors: `../ln-331-task-executor/SKILL.md`, `../ln-333-task-rework/SKILL.md`, `../ln-334-test-executor/SKILL.md`, `../ln-332-task-reviewer/SKILL.md`
- Auto-discovery: `CLAUDE.md`, `docs/tasks/kanban_board.md`
---
Version: 8.1.0 (Condensed orchestration, kept priority loop and quality delegation rules)
Last Updated: 2025-11-26

189
skills/ln-330-story-executor/diagram.html Normal file
View File

@@ -0,0 +1,189 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>ln-330-story-executor - State Diagram</title>
<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
<link rel="stylesheet" href="../shared/css/diagram.css">
</head>
<body>
<div class="container">
<header>
<h1>🔄 ln-330-story-executor</h1>
<p class="subtitle">Story Execution Orchestrator - State Diagram</p>
</header>
<div class="info-box">
<h3>📋 Workflow Overview</h3>
<ul>
<li><strong>Purpose:</strong> Orchestrate complete Story execution from tasks through quality gates to Story Done (FULL AUTOMATION)</li>
<li><strong>Priority Order:</strong> 🔴 To Review → 🟡 To Rework → 🟢 Todo (Phase 3 loop)</li>
<li><strong>Loop Control:</strong> Explicit LoopEntry/ReturnToLoop points with thick arrows (==>) for cycle clarity</li>
<li><strong>Phase 4 Delegation:</strong> ln-340-story-quality-gate Pass 1 (auto-verifies new tasks) → Pass 2 (auto-invoked after test task Done) → Story Done</li>
<li><strong>Key Feature:</strong> Lazy loading (metadata only in Phase 2, saves 10,000+ tokens)</li>
<li><strong>Self-Healing:</strong> Pass 1 creates fix/refactor/test task → auto-verifies (Backlog → Todo) → loops back to Phase 3</li>
<li><strong>Full Automation:</strong> Todo → In Progress → To Review → Done (no manual intervention)</li>
</ul>
</div>
<div class="legend">
<div class="legend-item">
<div class="legend-color color-discovery"></div>
<span>Discovery/Preparation</span>
</div>
<div class="legend-item">
<div class="legend-color color-loop"></div>
<span>Loop/Processing</span>
</div>
<div class="legend-item">
<div class="legend-color" style="background-color: #E1BEE7; border-color: #7B1FA2;"></div>
<span>Loop Control (Entry/Return)</span>
</div>
<div class="legend-item">
<div class="legend-color color-decision"></div>
<span>Decision Point</span>
</div>
<div class="legend-item">
<div class="legend-color color-action"></div>
<span>Action/Update</span>
</div>
<div class="legend-item">
<div class="legend-color color-critical"></div>
<span>Critical (Stop Condition)</span>
</div>
</div>
<div class="diagram-container">
<div class="mermaid">
graph TD
Start((Start:<br/>Execute Story)) --> Phase1[Phase 1: Discovery<br/>Auto-discover Team ID]
Phase1 --> Phase2[Phase 2: Story + Tasks Overview<br/>Load Story FULL description<br/>❌ Tasks metadata ONLY from kanban_board.md]
Phase2 --> KanbanCheck{kanban_board.md<br/>exists?}
KanbanCheck -->|No| SyncLinear[Fallback: Sync with Linear<br/>Fetch tasks metadata ONLY<br/>NO descriptions!]
SyncLinear --> LoopEntry
KanbanCheck -->|Yes| LoopEntry
%% Phase 3: Task Orchestration Loop
subgraph Phase3_Loop [⚙️ Phase 3: Task Orchestration Loop - Priority-Based (3 levels)]
direction TB
LoopEntry((Loop<br/>Entry)) --> Phase3
Phase3[Read kanban_board.md<br/>Count tasks by status]
Phase3 --> Priority0{🔴 PRIORITY 0<br/>Has To Review?}
Priority0 -->|Yes| InvokeReviewer[[ln-332-task-reviewer<br/>via Skill tool]]
InvokeReviewer -->|Task reviewed| ReloadAfterReview[Reload state]
ReloadAfterReview ==> LoopEntry
Priority0 -->|No| Priority1{🟡 PRIORITY 1<br/>Has To Rework?}
Priority1 -->|Yes| InvokeRework[[ln-333-task-rework<br/>via Skill tool]]
InvokeRework -->|Task fixed| ReloadAfterRework[Reload state]
ReloadAfterRework ==> LoopEntry
Priority1 -->|No| Priority2{🟢 PRIORITY 2<br/>Has Todo?}
Priority2 -->|Yes| InvokeExecutor[[ln-331-task-executor<br/>or ln-334-test-executor<br/>via Skill tool]]
InvokeExecutor -->|Task executed| ReloadAfterExec[Reload state]
ReloadAfterExec ==> LoopEntry
Priority2 -->|No| StopCondition{{Stop Condition:<br/>All Tasks Done}}
end
%% Phase 4: Story Review & Finalization (Delegation Pattern)
subgraph Phase4_Review [✅ Phase 4: Story Quality Delegation - Pass 1 & Pass 2]
direction TB
Phase4Start[All implementation tasks Done]
Phase4Start --> InvokePass1[Invoke ln-340-story-quality-gate Pass 1<br/>via Skill tool]
InvokePass1 --> Pass1Execution[Pass 1 executes:<br/>Code Quality → Regression → Manual Testing]
Pass1Execution --> Pass1Verdict{Pass 1 Verdict?}
Pass1Verdict -->|Test task created| AutoVerifyTest[Auto-verify via ln-320-story-validator<br/>Backlog → Todo]
Pass1Verdict -->|Fix/refactor task created| AutoVerifyFix[Auto-verify via ln-320-story-validator<br/>Backlog → Todo]
AutoVerifyTest --> LoopBackTest[GOTO Phase 3<br/>Execute test task]
AutoVerifyFix --> LoopBackFix[GOTO Phase 3<br/>Execute fix/refactor task]
LoopBackTest -.->|Test task Done| InvokePass2
LoopBackFix -.->|Fix Done| InvokePass1
InvokePass2[Update Story: In Progress → To Review<br/>Invoke ln-340-story-quality-gate Pass 2<br/>via Skill tool]
InvokePass2 --> Pass2Execution[Pass 2 executes:<br/>Test verification Priority ≥15]
Pass2Execution --> Pass2Verdict{Pass 2 Verdict?}
Pass2Verdict -->|PASS| StoryDone[Story status: To Review → Done<br/>Delete temp script<br/>Workflow complete]
Pass2Verdict -->|FAIL| CreatePass2Fix[Create fix tasks in Backlog<br/>Auto-verify → GOTO Phase 3]
end
StopCondition -.->|Trigger| Phase4Start
%% Self-healing: Return points
LoopBackTest -.-> ReturnToLoop
LoopBackFix -.-> ReturnToLoop
CreatePass2Fix -.-> ReturnToLoop
ReturnToLoop((Return to<br/>Orchestration)) ==> LoopEntry
StoryDone --> End((End))
%% Styling
classDef discovery fill:#E3F2FD,stroke:#1976D2,stroke-width:2px
classDef loop fill:#FFF9C4,stroke:#F57C00,stroke-width:2px
classDef decision fill:#FFE0B2,stroke:#E64A19,stroke-width:2px
classDef action fill:#C8E6C9,stroke:#388E3C,stroke-width:2px
classDef critical fill:#FFCDD2,stroke:#C62828,stroke-width:3px
classDef loopControl fill:#E1BEE7,stroke:#7B1FA2,stroke-width:2px
class Phase1,Phase2 discovery
class Phase3,InvokeReviewer,InvokeRework,InvokeExecutor,ReloadAfterReview,ReloadAfterRework,ReloadAfterExec loop
class Priority0,Priority1,Priority2,KanbanCheck,Pass1Verdict,Pass2Verdict decision
class Phase4Start,InvokePass1,Pass1Execution,InvokePass2,Pass2Execution,AutoVerifyTest,AutoVerifyFix,LoopBackTest,LoopBackFix,CreatePass2Fix,StoryDone action
class StopCondition critical
class LoopEntry,ReturnToLoop loopControl
</div>
</div>
<div class="info-box">
<h3>⚠️ Critical Rules</h3>
<ul>
<li><strong>Phase 2 - ABSOLUTE PROHIBITION:</strong> NEVER load full Task descriptions (saves 10,000+ tokens)</li>
<li><strong>Loop Mechanism:</strong> Reload kanban_board.md after every skill invocation to get fresh state</li>
<li><strong>Priority Enforcement:</strong> Priority 0 (To Review) → Priority 1 (To Rework) → Priority 2 (Todo)</li>
<li><strong>Phase 4 Automation:</strong> Full Story lifecycle executes automatically (Pass 1 → auto-verify new tasks → Pass 2 → Done)</li>
</ul>
</div>
<div class="info-box">
<h3>🔍 Phase 4: Story Quality Delegation (Orchestrator-Worker Pattern)</h3>
<ul>
<li><strong>Pass 1 Invocation:</strong> ln-330-story-executor delegates to ln-340-story-quality-gate Pass 1 (Code Quality → Regression → Manual Testing with Early Exit)</li>
<li><strong>Auto-Verification:</strong> New tasks (test/fix/refactor) created in Backlog are automatically verified by ln-320-story-validator (invoked via Skill tool)</li>
<li><strong>Loop Back:</strong> After auto-verification moves tasks to Todo, orchestration loop continues via Priority 2 (Todo execution)</li>
<li><strong>Pass 2 Invocation:</strong> When test task Done, Story status updates to To Review and ln-340-story-quality-gate Pass 2 is invoked automatically</li>
<li><strong>Story Done:</strong> Pass 2 verifies tests (Priority ≥15, 10-28 total), updates Story status to Done, workflow complete</li>
<li><strong>Self-Healing:</strong> Pass 2 failures create fix tasks in Backlog → ln-320-story-validator auto-verification → loop back to Phase 3</li>
</ul>
</div>
<footer>
<p>ln-330-story-executor v6.0.0 | Full automation: Todo → In Progress → To Review → Done (no manual intervention)</p>
<p>Diagram format: Mermaid.js | Orchestrator-Worker Pattern | Last updated: 2025-11-14</p>
</footer>
</div>
<script>
mermaid.initialize({
startOnLoad: true,
theme: 'default',
flowchart: {
useMaxWidth: true,
htmlLabels: true,
curve: 'stepBefore'
}
});
</script>
</body>
</html>

46
skills/ln-331-task-executor/SKILL.md Normal file
View File

@@ -0,0 +1,46 @@
---
name: ln-331-task-executor
description: Executes implementation tasks (Todo -> In Progress -> To Review). Follows KISS/YAGNI, guides, quality checks. Not for test tasks.
---
# Implementation Task Executor
Executes a single implementation (or refactor) task from Todo to To Review using the task description and linked guides.
## Purpose & Scope
- Handle one selected task only; never touch other tasks.
- Follow task Technical Approach/plan/AC; apply KISS/YAGNI and guide patterns.
- Update Linear/kanban for this task: Todo -> In Progress -> To Review.
- Run typecheck/lint; update docs/tests/config per task instructions.
- Not for test tasks (label "tests" goes to ln-334-test-executor).
## Workflow (concise)
1) **Load context:** Fetch full task description; read linked guides/manuals/ADRs; auto-discover team/config if needed.
2) **Pick task:** If ID provided, use it; otherwise list Todo tasks and select one.
3) **Start work:** Update this task to In Progress in Linear; move it in kanban (keep Epic/Story indent).
4) **Implement:** Follow checkboxes/plan; keep it simple; avoid hardcoded values; reuse existing components; update docs noted in Affected Components; update existing tests if impacted (no new tests here).
5) **Quality:** Run typecheck and lint (or project equivalents); ensure instructions in Existing Code Impact are addressed.
6) **Finish:** Mark task To Review in Linear; update kanban to To Review; add summary comment (what changed, tests run, docs touched).
## Critical Rules
- Single-task updates only; no bulk status changes.
- Keep language of the task (EN/RU) in edits/comments.
- No code snippets in the description; code lives in repo, not in Linear.
- No new test creation; only update existing tests if required.
- Preserve Foundation-First ordering from orchestrator; do not reorder tasks.
## Definition of Done
- Task selected and set to In Progress; kanban updated accordingly.
- Guides/manuals/ADRs read; approach aligned with task Technical Approach.
- Implementation completed per plan/AC; docs and impacted tests updated.
- Typecheck and lint passed (or project quality commands) with evidence in comment.
- Task set to To Review; kanban moved to To Review; summary comment added.
## Reference Files
- Task template: `../ln-311-task-creator/references/task_template_implementation.md`
- Guides/manuals/ADRs: `docs/guides/`, `docs/manuals/`, `docs/adrs/`
- Kanban format: `docs/tasks/kanban_board.md`
---
Version: 5.1.0 (Condensed executor flow and single-task safety)
Last Updated: 2025-11-26

Some files were not shown because too many files have changed in this diff Show More