@haaaiawd/anws 1.2.5 → 2.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +208 -172
- package/bin/cli.js +22 -9
- package/lib/adapters/index.js +157 -0
- package/lib/agents.js +136 -1
- package/lib/changelog.js +187 -0
- package/lib/copy.js +72 -1
- package/lib/diff.js +270 -0
- package/lib/init.js +143 -125
- package/lib/install-state.js +195 -0
- package/lib/manifest.js +184 -42
- package/lib/output.js +185 -13
- package/lib/prompt.js +284 -0
- package/lib/resources/index.js +27 -0
- package/lib/update.js +291 -83
- package/package.json +10 -6
- package/templates/.agents/skills/concept-modeler/SKILL.md +176 -0
- package/templates/{.agent → .agents}/skills/design-reviewer/SKILL.md +6 -6
- package/templates/.agents/skills/nexus-mapper/SKILL.md +306 -0
- package/templates/.agents/skills/nexus-mapper/references/language-customization.md +164 -0
- package/templates/.agents/skills/nexus-mapper/references/output-schema.md +298 -0
- package/templates/.agents/skills/nexus-mapper/references/probe-protocol.md +246 -0
- package/templates/.agents/skills/nexus-mapper/scripts/extract_ast.py +706 -0
- package/templates/.agents/skills/nexus-mapper/scripts/git_detective.py +194 -0
- package/templates/.agents/skills/nexus-mapper/scripts/languages.json +127 -0
- package/templates/.agents/skills/nexus-mapper/scripts/query_graph.py +556 -0
- package/templates/.agents/skills/nexus-mapper/scripts/requirements.txt +6 -0
- package/templates/{.agent → .agents}/skills/report-template/SKILL.md +11 -14
- package/templates/.agents/skills/report-template/references/REPORT_TEMPLATE.md +100 -0
- package/templates/{.agent → .agents}/skills/runtime-inspector/SKILL.md +1 -1
- package/templates/.agents/skills/sequential-thinking/SKILL.md +166 -0
- package/templates/.agents/skills/spec-writer/SKILL.md +108 -0
- package/templates/{.agent → .agents}/skills/spec-writer/references/prd_template.md +1 -1
- package/templates/{.agent → .agents}/skills/system-architect/SKILL.md +3 -3
- package/templates/.agents/skills/system-architect/references/rfc_template.md +59 -0
- package/templates/{.agent → .agents}/skills/system-designer/SKILL.md +6 -6
- package/templates/{.agent → .agents}/skills/system-designer/references/system-design-template.md +75 -25
- package/templates/{.agent → .agents}/skills/task-planner/SKILL.md +1 -1
- package/templates/.agents/skills/task-planner/references/TASK_TEMPLATE.md +144 -0
- package/templates/{.agent → .agents}/skills/task-reviewer/SKILL.md +4 -3
- package/templates/{.agent → .agents}/skills/tech-evaluator/SKILL.md +2 -2
- package/templates/{.agent → .agents}/skills/tech-evaluator/references/ADR_TEMPLATE.md +10 -0
- package/templates/{.agent → .agents}/workflows/blueprint.md +32 -27
- package/templates/{.agent → .agents}/workflows/challenge.md +21 -15
- package/templates/{.agent → .agents}/workflows/change.md +23 -14
- package/templates/{.agent → .agents}/workflows/craft.md +8 -19
- package/templates/{.agent → .agents}/workflows/design-system.md +81 -54
- package/templates/{.agent → .agents}/workflows/explore.md +6 -19
- package/templates/{.agent → .agents}/workflows/forge.md +30 -32
- package/templates/{.agent → .agents}/workflows/genesis.md +68 -56
- package/templates/.agents/workflows/probe.md +168 -0
- package/templates/{.agent → .agents}/workflows/quickstart.md +7 -12
- package/templates/.agents/workflows/upgrade.md +192 -0
- package/templates/AGENTS.md +66 -45
- package/templates/.agent/skills/build-inspector/SKILL.md +0 -83
- package/templates/.agent/skills/complexity-guard/SKILL.md +0 -71
- package/templates/.agent/skills/complexity-guard/references/anti_patterns.md +0 -21
- package/templates/.agent/skills/concept-modeler/SKILL.md +0 -112
- package/templates/.agent/skills/concept-modeler/prompts/GLOSSARY_PROMPT.md +0 -40
- package/templates/.agent/skills/concept-modeler/references/ENTITY_EXTRACTION_PROMPT.md +0 -299
- package/templates/.agent/skills/concept-modeler/scripts/glossary_gen.py +0 -66
- package/templates/.agent/skills/git-forensics/SKILL.md +0 -74
- package/templates/.agent/skills/git-forensics/references/ANALYSIS_METHODOLOGY.md +0 -193
- package/templates/.agent/skills/git-forensics/scripts/__pycache__/git_forensics.cpython-313.pyc +0 -0
- package/templates/.agent/skills/git-forensics/scripts/git_forensics.py +0 -615
- package/templates/.agent/skills/git-forensics/scripts/git_hotspots.py +0 -118
- package/templates/.agent/skills/report-template/references/REPORT_TEMPLATE.md +0 -100
- package/templates/.agent/skills/spec-writer/SKILL.md +0 -108
- package/templates/.agent/skills/system-architect/references/rfc_template.md +0 -59
- package/templates/.agent/skills/task-planner/references/TASK_TEMPLATE.md +0 -144
- package/templates/.agent/workflows/scout.md +0 -139
- /package/templates/{.agent → .agents}/skills/system-designer/references/system-design-detail-template.md +0 -0
|
@@ -1,118 +0,0 @@
|
|
|
1
|
-
import os
|
|
2
|
-
import argparse
|
|
3
|
-
import subprocess
|
|
4
|
-
import json
|
|
5
|
-
import csv
|
|
6
|
-
from datetime import datetime
|
|
7
|
-
try:
|
|
8
|
-
import lizard
|
|
9
|
-
except ImportError:
|
|
10
|
-
print("Error: lizard not installed. Run: pip install lizard")
|
|
11
|
-
exit(1)
|
|
12
|
-
|
|
13
|
-
def get_git_churn(repo_path: str, days: int) -> dict:
|
|
14
|
-
cmd = [
|
|
15
|
-
"git",
|
|
16
|
-
"-C", repo_path,
|
|
17
|
-
"log",
|
|
18
|
-
f"--since={days}.days.ago",
|
|
19
|
-
"--name-only",
|
|
20
|
-
"--format="
|
|
21
|
-
]
|
|
22
|
-
try:
|
|
23
|
-
result = subprocess.check_output(cmd, encoding='utf-8')
|
|
24
|
-
except subprocess.CalledProcessError as e:
|
|
25
|
-
print(f"Git command failed: {e}")
|
|
26
|
-
return {}
|
|
27
|
-
|
|
28
|
-
churn_map = {}
|
|
29
|
-
for line in result.splitlines():
|
|
30
|
-
if line.strip():
|
|
31
|
-
file_path = line.strip()
|
|
32
|
-
churn_map[file_path] = churn_map.get(file_path, 0) + 1
|
|
33
|
-
|
|
34
|
-
return churn_map
|
|
35
|
-
|
|
36
|
-
def get_complexity(repo_path: str, files: list) -> dict:
|
|
37
|
-
complexity_map = {}
|
|
38
|
-
for file_rel_path in files:
|
|
39
|
-
full_path = os.path.join(repo_path, file_rel_path)
|
|
40
|
-
if not os.path.exists(full_path):
|
|
41
|
-
continue
|
|
42
|
-
|
|
43
|
-
try:
|
|
44
|
-
analysis = lizard.analyze_file(full_path)
|
|
45
|
-
# Use average cyclomatic complexity (CCN) or max CCN
|
|
46
|
-
# Max CCN is often a better indicator of "scary code"
|
|
47
|
-
max_ccn = 0
|
|
48
|
-
for func in analysis.function_list:
|
|
49
|
-
if func.cyclomatic_complexity > max_ccn:
|
|
50
|
-
max_ccn = func.cyclomatic_complexity
|
|
51
|
-
|
|
52
|
-
# File length is also a complexity factor
|
|
53
|
-
nloc = analysis.nloc
|
|
54
|
-
|
|
55
|
-
complexity_map[file_rel_path] = {
|
|
56
|
-
"max_ccn": max_ccn,
|
|
57
|
-
"nloc": nloc,
|
|
58
|
-
"avg_ccn": analysis.average_cyclomatic_complexity
|
|
59
|
-
}
|
|
60
|
-
except Exception as e:
|
|
61
|
-
# lizard might fail on non-code files
|
|
62
|
-
pass
|
|
63
|
-
|
|
64
|
-
return complexity_map
|
|
65
|
-
|
|
66
|
-
def analyze_hotspots(repo_path: str, days: int, output_file: str):
|
|
67
|
-
print(f"Analyzing git churn for past {days} days...")
|
|
68
|
-
churn_data = get_git_churn(repo_path, days)
|
|
69
|
-
|
|
70
|
-
print("Analyzing code complexity...")
|
|
71
|
-
# Only analyze files that exist and have churn
|
|
72
|
-
target_files = [f for f in churn_data.keys()]
|
|
73
|
-
complexity_data = get_complexity(repo_path, target_files)
|
|
74
|
-
|
|
75
|
-
hotspots = []
|
|
76
|
-
for file, churn in churn_data.items():
|
|
77
|
-
if file in complexity_data:
|
|
78
|
-
comp = complexity_data[file]
|
|
79
|
-
hotspots.append({
|
|
80
|
-
"file": file,
|
|
81
|
-
"churn": churn,
|
|
82
|
-
"max_ccn": comp["max_ccn"],
|
|
83
|
-
"nloc": comp["nloc"],
|
|
84
|
-
# Simple score: Churn * CCN.
|
|
85
|
-
# Prompts usually care about this metric.
|
|
86
|
-
"debt_score": churn * comp["max_ccn"]
|
|
87
|
-
})
|
|
88
|
-
|
|
89
|
-
# Sort by debt score descending
|
|
90
|
-
hotspots.sort(key=lambda x: x["debt_score"], reverse=True)
|
|
91
|
-
|
|
92
|
-
# Output
|
|
93
|
-
result = {
|
|
94
|
-
"analysis_date": datetime.now().isoformat(),
|
|
95
|
-
"period_days": days,
|
|
96
|
-
"total_files_analyzed": len(hotspots),
|
|
97
|
-
"hotspots": hotspots[:50] # Top 50
|
|
98
|
-
}
|
|
99
|
-
|
|
100
|
-
if output_file:
|
|
101
|
-
with open(output_file, 'w') as f:
|
|
102
|
-
json.dump(result, f, indent=2)
|
|
103
|
-
print(f"Hotspot analysis saved to {output_file}")
|
|
104
|
-
else:
|
|
105
|
-
print(json.dumps(result, indent=2))
|
|
106
|
-
|
|
107
|
-
def main():
|
|
108
|
-
parser = argparse.ArgumentParser(description="Git Hotspot Analysis (Churn vs Complexity)")
|
|
109
|
-
parser.add_argument("--repo", default=".", help="Repository path")
|
|
110
|
-
parser.add_argument("--days", type=int, default=180, help="Analysis period in days")
|
|
111
|
-
parser.add_argument("--output", "-o", help="Output JSON file")
|
|
112
|
-
|
|
113
|
-
args = parser.parse_args()
|
|
114
|
-
|
|
115
|
-
analyze_hotspots(args.repo, args.days, args.output)
|
|
116
|
-
|
|
117
|
-
if __name__ == "__main__":
|
|
118
|
-
main()
|
|
@@ -1,100 +0,0 @@
|
|
|
1
|
-
# System Context Report
|
|
2
|
-
|
|
3
|
-
**Generated Date**: {{DATE}}
|
|
4
|
-
**Analysis Target**: {{SCOPE}}
|
|
5
|
-
|
|
6
|
-
## Executive Summary
|
|
7
|
-
> [One sentence summary of the system's state, e.g., "A robust Python backend with some technical debt in the Auth module."]
|
|
8
|
-
|
|
9
|
-
---
|
|
10
|
-
|
|
11
|
-
## 1. Component Inventory
|
|
12
|
-
|
|
13
|
-
### 1.1 Existing Components
|
|
14
|
-
| Component | Type | Path | Description |
|
|
15
|
-
|---|---|---|---|
|
|
16
|
-
| [Name] | [Service/UI/DB] | [Path] | [Brief Desc] |
|
|
17
|
-
|
|
18
|
-
### 1.2 Missing Components (Dark Matter)
|
|
19
|
-
> [!WARNING]
|
|
20
|
-
> The following components are missing but critical for production readiness.
|
|
21
|
-
|
|
22
|
-
| Component | Category | Why Needed | Impact if Missing |
|
|
23
|
-
|---|---|---|---|
|
|
24
|
-
| Error Handling | Infrastructure | No central error boundary found | Debugging will be difficult |
|
|
25
|
-
| Logging | Observability | No structured logging | Blind in production |
|
|
26
|
-
| Config Mgmt | Ops | Hardcoded secrets detected | Security risk |
|
|
27
|
-
|
|
28
|
-
---
|
|
29
|
-
|
|
30
|
-
## 2. Dependency Topology
|
|
31
|
-
|
|
32
|
-
### 2.1 Build Boundaries (Build Inspector)
|
|
33
|
-
> [Insert findings from `build-inspector`: Build Roots, Topology, Sidecar Warnings]
|
|
34
|
-
|
|
35
|
-
```mermaid
|
|
36
|
-
graph TD
|
|
37
|
-
A[Module A] --> B[Module B]
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
### 2.2 Logical Coupling (Git Forensics)
|
|
41
|
-
> [Insert Hotspot Matrix or Coupling Table]
|
|
42
|
-
|
|
43
|
-
| File A | File B | Coupling | Risk |
|
|
44
|
-
|---|---|---|---|
|
|
45
|
-
| auth.py | user_db.py | 85% | HIGH |
|
|
46
|
-
|
|
47
|
-
---
|
|
48
|
-
|
|
49
|
-
## 3. Risks & Warnings
|
|
50
|
-
|
|
51
|
-
### 3.1 IPC Contract Risks (Runtime Inspector)
|
|
52
|
-
> [!CAUTION]
|
|
53
|
-
> [List IPC surfaces with weak/no contracts found by `runtime-inspector`]
|
|
54
|
-
|
|
55
|
-
### 3.2 God Modules
|
|
56
|
-
> [List modules with excessive Ca (Afferent Coupling)]
|
|
57
|
-
|
|
58
|
-
### 3.3 Tech Debt Hotspots
|
|
59
|
-
> [List files with High Churn + High Complexity]
|
|
60
|
-
|
|
61
|
-
---
|
|
62
|
-
|
|
63
|
-
## 4. Implicit Constraints (Invariant Hunter)
|
|
64
|
-
|
|
65
|
-
### 4.1 Business Invariants
|
|
66
|
-
> [Rules that must never be broken]
|
|
67
|
-
- Order total must be >= 0
|
|
68
|
-
- User must verify email before payment
|
|
69
|
-
|
|
70
|
-
### 4.2 Assumptions
|
|
71
|
-
> [Unwritten assumptions found in code]
|
|
72
|
-
- "Network is always reliable" (No retry logic)
|
|
73
|
-
- "ID is always an integer"
|
|
74
|
-
|
|
75
|
-
### 4.3 Hardcoded Values
|
|
76
|
-
- API Keys
|
|
77
|
-
- Timeout values
|
|
78
|
-
|
|
79
|
-
---
|
|
80
|
-
|
|
81
|
-
## 5. Conceptual Model (Concept Modeler)
|
|
82
|
-
|
|
83
|
-
### 5.1 Ubiquitous Language
|
|
84
|
-
| Term | Definition |
|
|
85
|
-
|---|---|
|
|
86
|
-
| User | A registered end-user (not an admin) |
|
|
87
|
-
| Order | A purchase request |
|
|
88
|
-
|
|
89
|
-
### 5.2 Data Flows
|
|
90
|
-
> [Describe key flows]
|
|
91
|
-
|
|
92
|
-
---
|
|
93
|
-
|
|
94
|
-
## 6. Human Checkpoints
|
|
95
|
-
> [!IMPORTANT]
|
|
96
|
-
> Please confirm the following before proceeding to Blueprint Phase:
|
|
97
|
-
|
|
98
|
-
- [ ] Is the Component Inventory complete?
|
|
99
|
-
- [ ] Are the identified Risks acceptable for now?
|
|
100
|
-
- [ ] Have all Invariants been captured?
|
|
@@ -1,108 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: spec-writer
|
|
3
|
-
description: Transforms ambiguous user requests into rigorous Product Requirements Documents (PRDs). Use when requirements are vague or high-level.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# The Detective's Guide (需求侦探手册)
|
|
7
|
-
|
|
8
|
-
> "The hardest part of building software is deciding precisely what to build."
|
|
9
|
-
|
|
10
|
-
Your job is to kill ambiguity.
|
|
11
|
-
|
|
12
|
-
## ⚡ Quick Start
|
|
13
|
-
|
|
14
|
-
1. **Read Request (MANDATORY)**: Use `view_file` or context to identify "Vibe Words" (Fast, Modern, Easy).
|
|
15
|
-
2. **Deep Think (CRITICAL)**: You MUST call `sequential thinking` with 3-7 reasoning steps (depending on complexity) to:
|
|
16
|
-
* Extract User Stories (As a X, I want Y, so that Z)
|
|
17
|
-
* Identify ambiguities
|
|
18
|
-
* Draft clarifying questions
|
|
19
|
-
3. **Interrogate**: Present questions to user. DO NOT proceed without answers.
|
|
20
|
-
4. **Draft PRD (MANDATORY)**: Use `view_file references/prd_template.md` then `write_to_file` to create `genesis/v{N}/01_PRD.md`.
|
|
21
|
-
5. **Ambiguity Scan (MANDATORY)**: After drafting, run the 10-Dimension Ambiguity Scan (see below). Fix issues inline or mark `[ASSUMPTION]`.
|
|
22
|
-
6. **US Quality Gate (MANDATORY)**: Verify every User Story passes the quality checklist (see below).
|
|
23
|
-
|
|
24
|
-
## 🛑 Mandatory Steps
|
|
25
|
-
Before creating the PRD, you MUST:
|
|
26
|
-
1. Extract at least 3 clear User Stories.
|
|
27
|
-
2. Define at least 3 Non-Goals (what we're NOT building).
|
|
28
|
-
3. Clarify "Vibe Words" with the user (What does "Fast" mean to you? What does "Modern" imply?).
|
|
29
|
-
4. Use `write_to_file` to save output. DO NOT just print to chat.
|
|
30
|
-
|
|
31
|
-
After creating the PRD, you MUST:
|
|
32
|
-
5. Run the 10-Dimension Ambiguity Scan — fix or mark all `Partial`/`Missing` items.
|
|
33
|
-
6. Verify every User Story has: Priority / 独立可测 / 涉及系统 / 边界情况.
|
|
34
|
-
7. Ensure `[NEEDS CLARIFICATION]` tags ≤ 3 (hard limit). Excess → use reasonable defaults + `[ASSUMPTION]` tag.
|
|
35
|
-
|
|
36
|
-
## ✅ Completion Checklist
|
|
37
|
-
- [ ] PRD file created: `genesis/v{N}/01_PRD.md`
|
|
38
|
-
- [ ] Contains User Stories, Acceptance Criteria, Non-Goals
|
|
39
|
-
- [ ] Every requirement is testable/measurable
|
|
40
|
-
- [ ] User has approved the PRD
|
|
41
|
-
|
|
42
|
-
## 🛠️ The Techniques
|
|
43
|
-
|
|
44
|
-
### 1. Socratic Interrogation (苏格拉底追问)
|
|
45
|
-
* **User**: "I want it to be fast."
|
|
46
|
-
* **You**: "< 100ms p99? Or just UI optimistic updates?"
|
|
47
|
-
* *Goal*: Turn adjectives into numbers.
|
|
48
|
-
|
|
49
|
-
### 2. Context Compression (上下文压缩)
|
|
50
|
-
* **Input**: 500 lines of chat history.
|
|
51
|
-
* **Action**: Extract the *User Stories*. "As a User, I want X, so that Y."
|
|
52
|
-
* **Discard**: Implementation details discussed too early (e.g., "Use Redis").
|
|
53
|
-
|
|
54
|
-
### 3. Non-Goal Setting (画圈)
|
|
55
|
-
* Define what we are **NOT** doing.
|
|
56
|
-
* *Why*: Prevents scope creep. Prevents "What about X?" later.
|
|
57
|
-
|
|
58
|
-
## ⚠️ Detective's Code
|
|
59
|
-
|
|
60
|
-
1. **Contract First**: If you can't test it, don't write it.
|
|
61
|
-
2. **No Solutions**: Describe *what*, not *how*. Leave *how* to the Architect.
|
|
62
|
-
3. **User Centric**: Every requirement must trace back to a user value.
|
|
63
|
-
|
|
64
|
-
## 🧰 The Toolkit
|
|
65
|
-
* `references/prd_template.md`: The Product Requirements Document template.
|
|
66
|
-
|
|
67
|
-
## 🔍 10-Dimension Ambiguity Scan
|
|
68
|
-
|
|
69
|
-
After drafting the PRD, you **MUST** systematically scan it against these 10 dimensions. This replaces ad-hoc "any questions?" with a **repeatable, exhaustive** sweep.
|
|
70
|
-
|
|
71
|
-
For each dimension, mark status: `Clear` ✅ / `Partial` ⚠️ / `Missing` ❌
|
|
72
|
-
|
|
73
|
-
| # | Dimension | What to Check | Status |
|
|
74
|
-
|---|-----------|--------------|:------:|
|
|
75
|
-
| 1 | **Functional Scope & Behavior** | Core objectives / success criteria / explicit exclusions / user role distinctions | |
|
|
76
|
-
| 2 | **Domain & Data Model** | Entities, attributes, relationships / uniqueness rules / lifecycle & state transitions / data volume assumptions | |
|
|
77
|
-
| 3 | **Interaction & UX Flow** | Key user journeys / error, empty, loading states / accessibility & i18n | |
|
|
78
|
-
| 4 | **Non-Functional Quality** | Performance / scalability / reliability / observability / security & privacy / compliance | |
|
|
79
|
-
| 5 | **Integration & External** | External service failure modes / import-export formats / protocol version assumptions | |
|
|
80
|
-
| 6 | **Edge Cases & Failure** | Negative scenarios / rate limiting / concurrency conflict resolution | |
|
|
81
|
-
| 7 | **Constraints & Tradeoffs** | Technical constraints / explicit tradeoff records / rejected alternative archives | |
|
|
82
|
-
| 8 | **Terminology Consistency** | Canonical glossary / synonym normalization across PRD | |
|
|
83
|
-
| 9 | **Completion Signals** | Acceptance criteria testability / quantifiable DoD | |
|
|
84
|
-
| 10 | **Placeholders** | TODO markers / unquantified vague adjectives (fast, scalable, secure, intuitive, robust) | |
|
|
85
|
-
|
|
86
|
-
**Rules**:
|
|
87
|
-
- `Partial` or `Missing` items → rank by **Impact × Uncertainty**, pick **top 5** to ask user
|
|
88
|
-
- Ask **one question at a time**; provide your recommended answer; user can accept or customize
|
|
89
|
-
- After user answers → **atomically write** the answer into the corresponding PRD section (never leave contradictory text)
|
|
90
|
-
- **NEEDS CLARIFICATION hard limit ≤ 3** — if more remain, fill with reasonable defaults + `[ASSUMPTION: ...]` tag
|
|
91
|
-
- **Do NOT ask about these reasonable defaults**: industry-standard data retention, standard web/mobile performance expectations, user-friendly error messages with fallbacks, standard session-based or OAuth2 auth
|
|
92
|
-
|
|
93
|
-
## ✅ User Story Quality Gate
|
|
94
|
-
|
|
95
|
-
Every User Story in the PRD **MUST** pass these checks before the PRD is considered complete:
|
|
96
|
-
|
|
97
|
-
| Check | Requirement |
|
|
98
|
-
|-------|------------|
|
|
99
|
-
| **Unique ID** | Has `[REQ-XXX]` identifier for traceability |
|
|
100
|
-
| **Priority** | Marked P0 / P1 / P2 — P0 stories listed first |
|
|
101
|
-
| **独立可测** | Describes how this story can be **independently** demonstrated and verified |
|
|
102
|
-
| **涉及系统** | Lists specific system IDs (must align with `02_ARCHITECTURE_OVERVIEW.md`) |
|
|
103
|
-
| **Acceptance Criteria** | At least 1 Given-When-Then + at least 1 Error Case |
|
|
104
|
-
| **边界情况** | At least 1 boundary condition identified |
|
|
105
|
-
| **No Vibe Words** | No unquantified adjectives (fast → <100ms p99, scalable → support N users) |
|
|
106
|
-
| **User Value** | One sentence describing value to end user |
|
|
107
|
-
|
|
108
|
-
If any User Story fails a check → fix it before delivering the PRD.
|
|
@@ -1,59 +0,0 @@
|
|
|
1
|
-
# Request for Comments (RFC) / Technical Spec
|
|
2
|
-
|
|
3
|
-
**PRD Reference**: [Link to PRD]
|
|
4
|
-
**Feature**: [Feature Name]
|
|
5
|
-
**Status**: Draft
|
|
6
|
-
|
|
7
|
-
## 1. High-Level Design
|
|
8
|
-
### Architecture Diagram (Mermaid)
|
|
9
|
-
<!-- Use Mermaid to show data flow -->
|
|
10
|
-
```mermaid
|
|
11
|
-
graph TD
|
|
12
|
-
A[User] -->|Action| B(Component)
|
|
13
|
-
B -->|API Call| C{Service}
|
|
14
|
-
```
|
|
15
|
-
|
|
16
|
-
### Component Hierarchy
|
|
17
|
-
* `ParentComponent`
|
|
18
|
-
* `ChildA` (Props: x, y)
|
|
19
|
-
* `ChildB` (State: z)
|
|
20
|
-
|
|
21
|
-
## 2. API Contract (The "Signature")
|
|
22
|
-
<!-- CRITICAL: Define exact signatures. No hallucination allowed. -->
|
|
23
|
-
|
|
24
|
-
### Endpoints
|
|
25
|
-
* `POST /api/v1/resource`
|
|
26
|
-
* **Request Body**:
|
|
27
|
-
```typescript
|
|
28
|
-
interface CreateRequest {
|
|
29
|
-
field: string; // required
|
|
30
|
-
}
|
|
31
|
-
```
|
|
32
|
-
* **Response**: `200 OK` (Schema below)
|
|
33
|
-
|
|
34
|
-
### Function Interfaces
|
|
35
|
-
<!-- Signatures for key internal functions -->
|
|
36
|
-
```typescript
|
|
37
|
-
function calculateSomething(input: InputType): ResultType
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
## 3. Data Model Strategy
|
|
41
|
-
### Database Schema Changes
|
|
42
|
-
```sql
|
|
43
|
-
-- DDL goes here
|
|
44
|
-
CREATE TABLE ...
|
|
45
|
-
```
|
|
46
|
-
|
|
47
|
-
### State Management
|
|
48
|
-
* Global State: [e.g. Redux/Zustand slice]
|
|
49
|
-
* Local State: [e.g. React.useState]
|
|
50
|
-
|
|
51
|
-
## 4. Implementation Steps
|
|
52
|
-
<!-- Atomic, ordered steps -->
|
|
53
|
-
1. [Step 1: DB Migration]
|
|
54
|
-
2. [Step 2: API Backend]
|
|
55
|
-
3. [Step 3: Frontend UI]
|
|
56
|
-
|
|
57
|
-
## 5. Security & Risk
|
|
58
|
-
* **Auth**: [How is this secured?]
|
|
59
|
-
* **Validation**: [Input validation library?]
|
|
@@ -1,144 +0,0 @@
|
|
|
1
|
-
# Task Decomposition Template
|
|
2
|
-
|
|
3
|
-
**Project**: [Project Name]
|
|
4
|
-
**Blueprint Phase**: Approved
|
|
5
|
-
**RFC Reference**: `genesis/v{N}/02_ARCHITECTURE_OVERVIEW.md`
|
|
6
|
-
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
## 📋 Task List
|
|
10
|
-
|
|
11
|
-
### Legend
|
|
12
|
-
- **ID**: Unique task identifier (T001, T002...)
|
|
13
|
-
- **[P]**: Parallelizable (can run independently)
|
|
14
|
-
- **[Verification]**: Checkpoint task (manual/E2E validation)
|
|
15
|
-
- **User Story**: Maps to PRD (US01, US02...)
|
|
16
|
-
- **Done When**: Verification criterion
|
|
17
|
-
|
|
18
|
-
---
|
|
19
|
-
|
|
20
|
-
### Phase 1: Foundation
|
|
21
|
-
|
|
22
|
-
#### T001 - Database Schema Setup
|
|
23
|
-
- **User Story**: US01
|
|
24
|
-
- **Description**: Create `users` table with fields: `id`, `email`, `password_hash`, `created_at`.
|
|
25
|
-
- **Dependencies**: None
|
|
26
|
-
- **Done When**: `psql -c "\d users"` shows correct schema.
|
|
27
|
-
|
|
28
|
-
#### T002 - [P] Environment Configuration
|
|
29
|
-
- **User Story**: US01
|
|
30
|
-
- **Description**: Add `.env` file with `DATABASE_URL`, `JWT_SECRET`.
|
|
31
|
-
- **Dependencies**: None
|
|
32
|
-
- **Done When**: `docker-compose up` starts DB without errors.
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
---
|
|
36
|
-
|
|
37
|
-
### Phase 2: Core Logic
|
|
38
|
-
|
|
39
|
-
#### T003 - User Registration Endpoint
|
|
40
|
-
- **User Story**: US01
|
|
41
|
-
- **Description**: Implement `POST /api/register` that hashes password and stores user.
|
|
42
|
-
- **Dependencies**: T001 (DB Schema)
|
|
43
|
-
- **Done When**: `curl -X POST /api
|
|
44
|
-
|
|
45
|
-
#### T004 - [P] JWT Token Generation
|
|
46
|
-
- **User Story**: US01
|
|
47
|
-
- **Description**: Create `generate_token(user_id)` helper function.
|
|
48
|
-
- **Dependencies**: T002 (JWT_SECRET configured)
|
|
49
|
-
- **Done When**: Unit test `test_generate_token()` passes.
|
|
50
|
-
|
|
51
|
-
---
|
|
52
|
-
|
|
53
|
-
## 📊 Sprint 路线图
|
|
54
|
-
|
|
55
|
-
| Sprint | 代号 | 核心任务 | 退出标准 | 预估 |
|
|
56
|
-
|--------|------|---------|---------|------|
|
|
57
|
-
| S1 | Foundation | T001-T002 | DB 可连接 + 环境变量生效 | 1d |
|
|
58
|
-
| S2 | Core Logic | T003-T005 | 完整认证流程可运行 | 2d |
|
|
59
|
-
|
|
60
|
-
---
|
|
61
|
-
|
|
62
|
-
### Phase 3: Integration
|
|
63
|
-
|
|
64
|
-
#### T005 - Login Endpoint
|
|
65
|
-
- **User Story**: US01
|
|
66
|
-
- **Description**: Implement `POST /api/login` that validates credentials and returns JWT.
|
|
67
|
-
- **Dependencies**: T003 (User table populated), T004 (JWT generator ready)
|
|
68
|
-
- **Input**: T003 产出的 `users` 表 + T004 产出的 `generate_token()` 函数
|
|
69
|
-
- **Output**: `/api/login` 端点 (`src/routes/auth.js`)
|
|
70
|
-
- **Done When**:
|
|
71
|
-
1. Valid login returns `{token: "..."}`.
|
|
72
|
-
2. Invalid login returns 401.
|
|
73
|
-
|
|
74
|
-
#### INT-S2 - [MILESTONE] S2 集成验证 — Core Logic
|
|
75
|
-
- **User Story**: US01
|
|
76
|
-
- **Type**: Integration Verification (Sprint Gate)
|
|
77
|
-
- **Description**: 验证 S2 退出标准:完整认证流程可运行
|
|
78
|
-
- **Dependencies**: All S2 tasks (T003-T005)
|
|
79
|
-
- **Done When**:
|
|
80
|
-
1. Run `npm run dev` or equivalent
|
|
81
|
-
2. Register a new user via `/api/register`
|
|
82
|
-
3. Login with valid credentials → receives JWT token
|
|
83
|
-
4. Login with invalid credentials → receives 401 error
|
|
84
|
-
5. All unit tests pass (`npm test`)
|
|
85
|
-
6. No linter errors (`npm run lint`)
|
|
86
|
-
|
|
87
|
-
---
|
|
88
|
-
|
|
89
|
-
## 🔗 Dependency Graph
|
|
90
|
-
|
|
91
|
-
```
|
|
92
|
-
T001 (DB Schema)
|
|
93
|
-
→ T003 (Register)
|
|
94
|
-
→ T005 (Login)
|
|
95
|
-
|
|
96
|
-
T002 (Env Config) [P]
|
|
97
|
-
→ T004 (JWT Helper) [P]
|
|
98
|
-
→ T005 (Login)
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
---
|
|
102
|
-
|
|
103
|
-
## 📊 Summary
|
|
104
|
-
|
|
105
|
-
| Phase | Total Tasks | Parallelizable |
|
|
106
|
-
|-------|-------------|----------------|
|
|
107
|
-
| 1 | 2 | 1 |
|
|
108
|
-
| 2 | 2 | 1 |
|
|
109
|
-
| 3 | 1 | 0 |
|
|
110
|
-
| **Total** | **5** | **2** |
|
|
111
|
-
|
|
112
|
-
---
|
|
113
|
-
|
|
114
|
-
## ✅ Acceptance Criteria
|
|
115
|
-
|
|
116
|
-
Before marking Blueprint as complete:
|
|
117
|
-
- [ ] All tasks have unique IDs
|
|
118
|
-
- [ ] Dependencies are explicit (→ notation)
|
|
119
|
-
- [ ] Each task has "Done When" criterion
|
|
120
|
-
- [ ] No task contains actual code (only descriptions <10 lines)
|
|
121
|
-
- [ ] Total estimated time is realistic
|
|
122
|
-
- [ ] User has approved this task list
|
|
123
|
-
|
|
124
|
-
---
|
|
125
|
-
|
|
126
|
-
## 🚫 Anti-Patterns to Avoid
|
|
127
|
-
|
|
128
|
-
❌ **Bad Task**:
|
|
129
|
-
```
|
|
130
|
-
T001 - Build Authentication System
|
|
131
|
-
- Implement everything related to auth
|
|
132
|
-
- Make it secure and fast
|
|
133
|
-
```
|
|
134
|
-
|
|
135
|
-
✅ **Good Task**:
|
|
136
|
-
```
|
|
137
|
-
T001 - Database Schema Setup
|
|
138
|
-
- Description: Create `users` table with `id`, `email`, `password_hash`.
|
|
139
|
-
- Done When: `psql -c "\d users"` shows correct schema.
|
|
140
|
-
```
|
|
141
|
-
|
|
142
|
-
---
|
|
143
|
-
|
|
144
|
-
**Next Step**: Proceed to `/build` workflow to implement tasks sequentially.
|
|
@@ -1,139 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
description: 探测系统风险、隐藏耦合和"改了就炸"的暗坑,通过 Git 热点分析和 Gap Analysis 产出风险报告,适用于接手遗留项目或重大变更前。
|
|
3
|
-
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# /scout
|
|
7
|
-
|
|
8
|
-
<phase_context>
|
|
9
|
-
你是 **Scout 2.0 - 结构拆解专家**。
|
|
10
|
-
|
|
11
|
-
**核心使命**:
|
|
12
|
-
在架构更新 (`genesis/v{N}`) 之前或之后,探测系统风险、暗坑和耦合。
|
|
13
|
-
Scout 的发现将作为**输入**反馈给 Architectural Overview。
|
|
14
|
-
|
|
15
|
-
**Output Goal**: `genesis/v{N}/00_SCOUT_REPORT.md`
|
|
16
|
-
</phase_context>
|
|
17
|
-
|
|
18
|
-
---
|
|
19
|
-
|
|
20
|
-
## ⚠️ CRITICAL 流程约束
|
|
21
|
-
|
|
22
|
-
> [!IMPORTANT]
|
|
23
|
-
> Scout 不修改架构,只**观测**和**报告**。
|
|
24
|
-
> 你的报告应该被 Genesis 过程参考。
|
|
25
|
-
|
|
26
|
-
> [!NOTE]
|
|
27
|
-
> **Scout 双模式说明**:
|
|
28
|
-
> - **模式 A (Genesis 前)**: 侦察遗留代码,产出作为 genesis 的输入
|
|
29
|
-
> - **模式 B (Genesis 后)**: 验证设计与代码的一致性 (Gap Analysis)
|
|
30
|
-
>
|
|
31
|
-
> 判断方式: 如果 `genesis/v{N}/concept_model.json` 存在 → 模式 B,Step 5 执行对比
|
|
32
|
-
> 如果不存在 → 模式 A,Step 5 跳过对比,仅提取代码中的概念
|
|
33
|
-
|
|
34
|
-
---
|
|
35
|
-
|
|
36
|
-
## Step 1: 建立大局观 (System Fingerprint)
|
|
37
|
-
|
|
38
|
-
1. **扫描根目录**: 列出项目根目录下的所有文件和文件夹
|
|
39
|
-
2. **获取当前架构上下文** (Optional):
|
|
40
|
-
- 如果存在 `genesis/v{N}`,读取其 `02_ARCHITECTURE_OVERVIEW.md` 以对比"计划"与"现实"。
|
|
41
|
-
|
|
42
|
-
---
|
|
43
|
-
|
|
44
|
-
## Step 2: 拆解构建系统 (Build Topology)
|
|
45
|
-
|
|
46
|
-
**目标**: 识别项目的构建边界和产物关系。
|
|
47
|
-
|
|
48
|
-
1. **调用技能**: `build-inspector`
|
|
49
|
-
2. **执行步骤**:
|
|
50
|
-
- 定位所有构建配置文件 (package.json, Cargo.toml, go.mod, Makefile 等)
|
|
51
|
-
- 判断是否有统一管理 (workspace/monorepo)
|
|
52
|
-
- 识别最终产物 (binary, bundle, docker image)
|
|
53
|
-
3. **输出要点**:
|
|
54
|
-
- Build Roots 列表
|
|
55
|
-
- 拓扑类型 (Monolith / Workspace / Polyrepo)
|
|
56
|
-
- ⚠️ 标记跨根依赖风险
|
|
57
|
-
|
|
58
|
-
---
|
|
59
|
-
|
|
60
|
-
## Step 3: 拆解运行时通信 (Runtime Topology)
|
|
61
|
-
|
|
62
|
-
**目标**: 追踪进程间通信和契约状态。
|
|
63
|
-
|
|
64
|
-
1. **调用技能**: `runtime-inspector`
|
|
65
|
-
2. **执行步骤**:
|
|
66
|
-
- 识别所有入口点 (main 函数)
|
|
67
|
-
- 追踪进程生成链 (spawn/fork)
|
|
68
|
-
- 检测 IPC 通道和协议定义
|
|
69
|
-
3. **输出要点**:
|
|
70
|
-
- Process Roots 和 Spawning Chains
|
|
71
|
-
- Contract Status (Strong / Weak / None)
|
|
72
|
-
- ⚠️ 标记僵尸进程和协议漂移风险
|
|
73
|
-
|
|
74
|
-
---
|
|
75
|
-
|
|
76
|
-
## Step 4: 拆解历史耦合 (Temporal Topology)
|
|
77
|
-
|
|
78
|
-
**目标**: 从 Git 历史发现隐藏的耦合关系。
|
|
79
|
-
|
|
80
|
-
1. **调用技能**: `git-forensics`
|
|
81
|
-
2. **执行步骤**:
|
|
82
|
-
- 分析变更频率和耦合对
|
|
83
|
-
- 交叉标注构建根信息
|
|
84
|
-
- 定位热点模块 (高 Churn × 高 Complexity)
|
|
85
|
-
3. **输出要点**:
|
|
86
|
-
- Coupling Pairs (标注构建根)
|
|
87
|
-
- Hotspots 和孤儿文件
|
|
88
|
-
- ⚠️ 重点标记跨根耦合
|
|
89
|
-
|
|
90
|
-
---
|
|
91
|
-
|
|
92
|
-
## Step 5: 领域概念建模 (Domain Concept Modeling)
|
|
93
|
-
|
|
94
|
-
**目标**: 提取*当前代码实现中*的隐式概念。
|
|
95
|
-
|
|
96
|
-
1. **调用技能**: `concept-modeler`
|
|
97
|
-
2. **对比**: 将代码中的概念与 `genesis/v{N}/concept_model.json` 进行对比 (如果存在)。
|
|
98
|
-
- *Gap Analysis*: "文档里说有 User 实体,但代码里只有 Account 实体?"
|
|
99
|
-
|
|
100
|
-
---
|
|
101
|
-
|
|
102
|
-
## Step 6: 冲突与风险分析
|
|
103
|
-
|
|
104
|
-
**目标**: 识别 "Change Impact"。
|
|
105
|
-
|
|
106
|
-
1. **如果你正在服务于一次 Genesis 更新**:
|
|
107
|
-
- 结合 `genesis/v{N}/01_PRD.md` (新需求)。
|
|
108
|
-
- 分析这些新需求会触碰哪些 "Landmines" (Git Hotspots)。
|
|
109
|
-
|
|
110
|
-
---
|
|
111
|
-
|
|
112
|
-
## Step 7: 生成报告
|
|
113
|
-
|
|
114
|
-
**目标**: 保存带有时间戳的报告,防止覆盖历史记录。
|
|
115
|
-
|
|
116
|
-
保存报告到 `genesis/v{N}/00_SCOUT_REPORT.md`
|
|
117
|
-
|
|
118
|
-
(注意:如果版本不存在,默认为 v1)
|
|
119
|
-
|
|
120
|
-
确保 `genesis/v{N}/` 目录存在。
|
|
121
|
-
|
|
122
|
-
**报告必须包含**:
|
|
123
|
-
1. **System Fingerprint**
|
|
124
|
-
2. **Gap Analysis** (Document vs Code)
|
|
125
|
-
3. **Risk Matrix** (Hotspots, IPC Risks)
|
|
126
|
-
|
|
127
|
-
<completion_criteria>
|
|
128
|
-
- ✅ 建立了系统指纹
|
|
129
|
-
- ✅ 发现了文档与代码的 Gap
|
|
130
|
-
- ✅ 产出了带有时间戳的风险报告
|
|
131
|
-
</completion_criteria>
|
|
132
|
-
|
|
133
|
-
---
|
|
134
|
-
|
|
135
|
-
## 🔀 Handoffs
|
|
136
|
-
|
|
137
|
-
完成本工作流后,根据情况选择:
|
|
138
|
-
|
|
139
|
-
- **启动新版本架构** → `/genesis` — 基于侦察发现启动架构重构 *(发现需要重大重构时)*
|
|
File without changes
|