mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-10 17:11:04 +08:00
feat: Add templates for epics, product brief, and requirements documentation
- Introduced a comprehensive template for generating epics and stories in Phase 5, including an index and individual epic files. - Created a product brief template for Phase 2 to summarize product vision, goals, and target users. - Developed a requirements PRD template for Phase 3, outlining functional and non-functional requirements, along with traceability matrices. feat: Implement tech debt roles for assessment, execution, planning, scanning, validation, and analysis - Added roles for tech debt assessment, executor, planner, scanner, validator, and analyst, each with defined phases and processes for managing technical debt. - Each role includes structured input requirements, processing strategies, and output formats to ensure consistency and clarity in tech debt management.
This commit is contained in:
catlog22
96
.claude/skills/team-lifecycle-v4/specs/knowledge-transfer.md
Normal file
96
.claude/skills/team-lifecycle-v4/specs/knowledge-transfer.md
Normal file
@@ -0,0 +1,96 @@
|
||||
# Knowledge Transfer Protocols
|
||||
|
||||
## 1. Transfer Channels
|
||||
|
||||
| Channel | Method | Producer | Consumer |
|
||||
|---------|--------|----------|----------|
|
||||
| Artifacts | Files in `<session>/artifacts/` | Task executor | Next task in pipeline |
|
||||
| State Updates | `team_msg(type="state_update")` | Task executor | Coordinator + downstream |
|
||||
| Wisdom | Append to `<session>/wisdom/*.md` | Any role | All roles |
|
||||
| Context Accumulator | In-memory aggregation | Inner loop only | Current task |
|
||||
| Exploration Cache | `<session>/explorations/` | Analyst / researcher | All roles |
|
||||
|
||||
## 2. Context Loading Protocol (Before Task Execution)
|
||||
|
||||
Every role MUST load context in this order before starting work.
|
||||
|
||||
| Step | Action | Required |
|
||||
|------|--------|----------|
|
||||
| 1 | `team_msg(operation="get_state", role=<upstream>)` | Yes |
|
||||
| 2 | Read artifact files from upstream state's `ref` paths | Yes |
|
||||
| 3 | Read `<session>/wisdom/*.md` if exists | Yes |
|
||||
| 4 | Check `<session>/explorations/cache-index.json` before new exploration | If exploring |
|
||||
|
||||
**Loading rules**:
|
||||
- Never skip step 1 -- state contains key decisions and findings
|
||||
- If `ref` path in state does not exist, log warning and continue
|
||||
- Wisdom files are append-only -- read all entries, newest last
|
||||
|
||||
## 3. Context Publishing Protocol (After Task Completion)
|
||||
|
||||
| Step | Action | Required |
|
||||
|------|--------|----------|
|
||||
| 1 | Write deliverable to `<session>/artifacts/<task-id>-<name>.md` | Yes |
|
||||
| 2 | Send `team_msg(type="state_update")` with payload (see schema below) | Yes |
|
||||
| 3 | Append wisdom entries for learnings, decisions, issues found | If applicable |
|
||||
|
||||
## 4. State Update Schema
|
||||
|
||||
Sent via `team_msg(type="state_update")` on task completion.
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "task_complete",
|
||||
"task_id": "<TASK-NNN>",
|
||||
"ref": "<session>/artifacts/<filename>",
|
||||
"key_findings": [
|
||||
"Finding 1",
|
||||
"Finding 2"
|
||||
],
|
||||
"decisions": [
|
||||
"Decision with rationale"
|
||||
],
|
||||
"files_modified": [
|
||||
"path/to/file.ts"
|
||||
],
|
||||
"verification": "self-validated | peer-reviewed | tested"
|
||||
}
|
||||
```
|
||||
|
||||
**Field rules**:
|
||||
- `ref`: Always an artifact path, never inline content
|
||||
- `key_findings`: Max 5 items, each under 100 chars
|
||||
- `decisions`: Include rationale, not just the choice
|
||||
- `files_modified`: Only for implementation tasks
|
||||
- `verification`: One of `self-validated`, `peer-reviewed`, `tested`
|
||||
|
||||
## 5. Exploration Cache Protocol
|
||||
|
||||
Prevents redundant research across tasks and discussion rounds.
|
||||
|
||||
| Step | Action |
|
||||
|------|--------|
|
||||
| 1 | Read `<session>/explorations/cache-index.json` |
|
||||
| 2 | If angle already explored, read cached result from `explore-<angle>.json` |
|
||||
| 3 | If not cached, perform exploration |
|
||||
| 4 | Write result to `<session>/explorations/explore-<angle>.json` |
|
||||
| 5 | Update `cache-index.json` with new entry |
|
||||
|
||||
**cache-index.json format**:
|
||||
```json
|
||||
{
|
||||
"entries": [
|
||||
{
|
||||
"angle": "competitor-analysis",
|
||||
"file": "explore-competitor-analysis.json",
|
||||
"created_by": "RESEARCH-001",
|
||||
"timestamp": "2026-01-15T10:30:00Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Rules**:
|
||||
- Cache key is the exploration `angle` (normalized to kebab-case)
|
||||
- Cache entries never expire within a session
|
||||
- Any role can read cached explorations; only the creator updates them
|
||||
113
.claude/skills/team-lifecycle-v4/specs/pipelines.md
Normal file
113
.claude/skills/team-lifecycle-v4/specs/pipelines.md
Normal file
@@ -0,0 +1,113 @@
|
||||
# Pipeline Definitions
|
||||
|
||||
## 1. Pipeline Selection Criteria
|
||||
|
||||
| Keywords | Pipeline |
|
||||
|----------|----------|
|
||||
| spec, design, document, requirements | `spec-only` |
|
||||
| implement, build, fix, code | `impl-only` |
|
||||
| full, lifecycle, end-to-end | `full-lifecycle` |
|
||||
| frontend, UI, react, vue | `fe-only` or `fullstack` |
|
||||
| Ambiguous / unclear | AskUserQuestion |
|
||||
|
||||
## 2. Spec-Only Pipeline
|
||||
|
||||
**6 tasks, 3 discussion rounds**
|
||||
|
||||
```
|
||||
RESEARCH-001(+D1) -> DRAFT-001 -> DRAFT-002(+D2) -> DRAFT-003 -> DRAFT-004 -> QUALITY-001(+D3)
|
||||
```
|
||||
|
||||
| Task | Role | Description | Discuss |
|
||||
|------|------|-------------|---------|
|
||||
| RESEARCH-001 | analyst | Research domain, competitors, constraints | D1: scope alignment |
|
||||
| DRAFT-001 | writer | Product brief, self-validate | - |
|
||||
| DRAFT-002 | writer | Requirements PRD | D2: requirements review |
|
||||
| DRAFT-003 | writer | Architecture design, self-validate | - |
|
||||
| DRAFT-004 | writer | Epics & stories, self-validate | - |
|
||||
| QUALITY-001 | reviewer | Quality gate scoring | D3: readiness decision |
|
||||
|
||||
**Checkpoint**: After QUALITY-001 -- pause for user approval before any implementation.
|
||||
|
||||
## 3. Impl-Only Pipeline
|
||||
|
||||
**4 tasks, 0 discussion rounds**
|
||||
|
||||
```
|
||||
PLAN-001 -> IMPL-001 -> TEST-001 + REVIEW-001
|
||||
```
|
||||
|
||||
| Task | Role | Description |
|
||||
|------|------|-------------|
|
||||
| PLAN-001 | planner | Break down into implementation steps, assess complexity |
|
||||
| IMPL-001 | implementer | Execute implementation plan |
|
||||
| TEST-001 | tester | Validate against acceptance criteria |
|
||||
| REVIEW-001 | reviewer | Code review |
|
||||
|
||||
TEST-001 and REVIEW-001 run in parallel after IMPL-001 completes.
|
||||
|
||||
## 4. Full-Lifecycle Pipeline
|
||||
|
||||
**10 tasks = spec-only (6) + impl (4)**
|
||||
|
||||
```
|
||||
[Spec pipeline] -> PLAN-001(blockedBy: QUALITY-001) -> IMPL-001 -> TEST-001 + REVIEW-001
|
||||
```
|
||||
|
||||
PLAN-001 is blocked until QUALITY-001 passes and user approves the checkpoint.
|
||||
|
||||
## 5. Frontend Pipelines
|
||||
|
||||
| Pipeline | Description |
|
||||
|----------|-------------|
|
||||
| `fe-only` | Frontend implementation only: PLAN-001 -> IMPL-001 (fe-implementer) -> TEST-001 + REVIEW-001 |
|
||||
| `fullstack` | Backend + frontend: PLAN-001 -> IMPL-001 (backend) + IMPL-002 (frontend) -> TEST-001 + REVIEW-001 |
|
||||
| `full-lifecycle-fe` | Full spec pipeline -> fullstack impl pipeline |
|
||||
|
||||
## 6. Conditional Routing
|
||||
|
||||
PLAN-001 outputs a complexity assessment that determines the impl topology.
|
||||
|
||||
| Complexity | Modules | Route |
|
||||
|------------|---------|-------|
|
||||
| Low | 1-2 | PLAN-001 -> IMPL-001 -> TEST + REVIEW |
|
||||
| Medium | 3-4 | PLAN-001 -> ORCH-001 -> IMPL-{1..N} (parallel) -> TEST + REVIEW |
|
||||
| High | 5+ | PLAN-001 -> ARCH-001 -> ORCH-001 -> IMPL-{1..N} -> TEST + REVIEW |
|
||||
|
||||
- **ORCH-001** (orchestrator): Coordinates parallel IMPL tasks, manages dependencies
|
||||
- **ARCH-001** (architect): Detailed architecture decisions before orchestration
|
||||
|
||||
## 7. Task Metadata Registry
|
||||
|
||||
| Task ID | Role | Phase | Depends On | Discuss | Priority |
|
||||
|---------|------|-------|------------|---------|----------|
|
||||
| RESEARCH-001 | analyst | research | - | D1 | P0 |
|
||||
| DRAFT-001 | writer | product-brief | RESEARCH-001 | - | P0 |
|
||||
| DRAFT-002 | writer | requirements | DRAFT-001 | D2 | P0 |
|
||||
| DRAFT-003 | writer | architecture | DRAFT-002 | - | P0 |
|
||||
| DRAFT-004 | writer | epics | DRAFT-003 | - | P0 |
|
||||
| QUALITY-001 | reviewer | readiness | DRAFT-004 | D3 | P0 |
|
||||
| PLAN-001 | planner | planning | QUALITY-001 (or user input) | - | P0 |
|
||||
| ARCH-001 | architect | arch-detail | PLAN-001 | - | P1 |
|
||||
| ORCH-001 | orchestrator | orchestration | PLAN-001 or ARCH-001 | - | P1 |
|
||||
| IMPL-001 | implementer | implementation | PLAN-001 or ORCH-001 | - | P0 |
|
||||
| IMPL-{N} | implementer | implementation | ORCH-001 | - | P0 |
|
||||
| TEST-001 | tester | validation | IMPL-* | - | P0 |
|
||||
| REVIEW-001 | reviewer | review | IMPL-* | - | P0 |
|
||||
|
||||
## 8. Dynamic Specialist Injection
|
||||
|
||||
When task content or user request matches trigger keywords, inject a specialist task.
|
||||
|
||||
| Trigger Keywords | Specialist Role | Task Prefix | Priority | Insert After |
|
||||
|------------------|----------------|-------------|----------|--------------|
|
||||
| security, vulnerability, OWASP | security-expert | SECURITY-* | P0 | PLAN |
|
||||
| performance, optimization, latency | performance-optimizer | PERF-* | P1 | IMPL |
|
||||
| data, pipeline, ETL, migration | data-engineer | DATA-* | P0 | parallel with IMPL |
|
||||
| devops, CI/CD, deployment, infra | devops-engineer | DEVOPS-* | P1 | IMPL |
|
||||
| ML, model, training, inference | ml-engineer | ML-* | P0 | parallel with IMPL |
|
||||
|
||||
**Injection rules**:
|
||||
- Specialist tasks inherit the session context and wisdom
|
||||
- They publish state_update on completion like any other task
|
||||
- P0 specialists block downstream tasks; P1 run in parallel
|
||||
130
.claude/skills/team-lifecycle-v4/specs/quality-gates.md
Normal file
130
.claude/skills/team-lifecycle-v4/specs/quality-gates.md
Normal file
@@ -0,0 +1,130 @@
|
||||
# Quality Gates
|
||||
|
||||
## 1. Quality Thresholds
|
||||
|
||||
| Result | Score | Action |
|
||||
|--------|-------|--------|
|
||||
| Pass | >= 80% | Proceed to next phase |
|
||||
| Review | 60-79% | Revise flagged items, re-evaluate |
|
||||
| Fail | < 60% | Return to producer for rework |
|
||||
|
||||
## 2. Scoring Dimensions
|
||||
|
||||
| Dimension | Weight | Criteria |
|
||||
|-----------|--------|----------|
|
||||
| Completeness | 25% | All required sections present with substantive content |
|
||||
| Consistency | 25% | Terminology, formatting, cross-references are uniform |
|
||||
| Traceability | 25% | Clear chain: Goals -> Requirements -> Architecture -> Stories |
|
||||
| Depth | 25% | ACs are testable, ADRs justified, stories estimable |
|
||||
|
||||
**Score** = weighted average of all dimensions (0-100 per dimension).
|
||||
|
||||
## 3. Per-Phase Quality Gates
|
||||
|
||||
### Phase 2: Product Brief
|
||||
|
||||
| Check | Pass Criteria |
|
||||
|-------|---------------|
|
||||
| Vision statement | Clear, one-paragraph, measurable outcome |
|
||||
| Problem definition | Specific pain points with evidence |
|
||||
| Target users | Defined personas or segments |
|
||||
| Success goals | Quantifiable metrics (KPIs) |
|
||||
| Success metrics | Measurement method specified |
|
||||
|
||||
### Phase 3: Requirements PRD
|
||||
|
||||
| Check | Pass Criteria |
|
||||
|-------|---------------|
|
||||
| Functional requirements | Each has unique ID (FR-NNN) |
|
||||
| Acceptance criteria | Testable given/when/then format |
|
||||
| Prioritization | MoSCoW applied to all requirements |
|
||||
| User stories | Format: As a [role], I want [goal], so that [benefit] |
|
||||
| Non-functional reqs | Performance, security, scalability addressed |
|
||||
|
||||
### Phase 4: Architecture
|
||||
|
||||
| Check | Pass Criteria |
|
||||
|-------|---------------|
|
||||
| Component diagram | All major components identified with boundaries |
|
||||
| Tech stack | Each choice justified against alternatives |
|
||||
| ADRs | At least 1 ADR per major decision, with status |
|
||||
| Data model | Entities, relationships, key fields defined |
|
||||
| Integration points | APIs, protocols, data formats specified |
|
||||
|
||||
### Phase 5: Epics & Stories
|
||||
|
||||
| Check | Pass Criteria |
|
||||
|-------|---------------|
|
||||
| Epic count | 2-8 epics (too few = too broad, too many = too granular) |
|
||||
| MVP subset | Clearly marked MVP epics/stories |
|
||||
| Stories per epic | 3-12 stories each |
|
||||
| Story format | Title, description, ACs, estimate present |
|
||||
|
||||
### Phase 6: Readiness Gate
|
||||
|
||||
| Check | Pass Criteria |
|
||||
|-------|---------------|
|
||||
| All docs exist | Brief, PRD, Architecture, Epics all present |
|
||||
| Cross-refs valid | All document references resolve correctly |
|
||||
| Overall score | >= 60% across all dimensions |
|
||||
| No P0 issues | Zero Error-class issues outstanding |
|
||||
|
||||
## 4. Cross-Document Validation
|
||||
|
||||
| Source | Target | Validation |
|
||||
|--------|--------|------------|
|
||||
| Brief goals | PRD requirements | Every goal has >= 1 requirement |
|
||||
| PRD requirements | Architecture components | Every requirement maps to a component |
|
||||
| PRD requirements | Epic stories | Every requirement covered by >= 1 story |
|
||||
| Architecture components | Epic stories | Every component has implementation stories |
|
||||
| Brief success metrics | Epic ACs | Metrics traceable to acceptance criteria |
|
||||
|
||||
## 5. Code Review Dimensions
|
||||
|
||||
For REVIEW-* tasks during implementation phases.
|
||||
|
||||
### Quality
|
||||
|
||||
| Check | Severity |
|
||||
|-------|----------|
|
||||
| Empty catch blocks | Error |
|
||||
| `as any` type casts | Warning |
|
||||
| `@ts-ignore` / `@ts-expect-error` | Warning |
|
||||
| `console.log` in production code | Warning |
|
||||
| Unused imports/variables | Info |
|
||||
|
||||
### Security
|
||||
|
||||
| Check | Severity |
|
||||
|-------|----------|
|
||||
| Hardcoded secrets/credentials | Error |
|
||||
| SQL injection vectors | Error |
|
||||
| `eval()` or `Function()` usage | Error |
|
||||
| `innerHTML` assignment | Warning |
|
||||
| Missing input validation | Warning |
|
||||
|
||||
### Architecture
|
||||
|
||||
| Check | Severity |
|
||||
|-------|----------|
|
||||
| Circular dependencies | Error |
|
||||
| Deep cross-boundary imports (3+ levels) | Warning |
|
||||
| Files > 500 lines | Warning |
|
||||
| Functions > 50 lines | Info |
|
||||
|
||||
### Requirements Coverage
|
||||
|
||||
| Check | Severity |
|
||||
|-------|----------|
|
||||
| Core functionality implemented | Error if missing |
|
||||
| Acceptance criteria covered | Error if missing |
|
||||
| Edge cases handled | Warning |
|
||||
| Error states handled | Warning |
|
||||
|
||||
## 6. Issue Classification
|
||||
|
||||
| Class | Label | Action |
|
||||
|-------|-------|--------|
|
||||
| Error | Must fix | Blocks progression, must resolve before proceeding |
|
||||
| Warning | Should fix | Should resolve, can proceed with justification |
|
||||
| Info | Nice to have | Optional improvement, log for future |
|
||||
Reference in New Issue
Block a user