specdacular 0.1.0 → 0.1.1
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 +151 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
# Specdacular
|
|
2
|
+
|
|
3
|
+
**Feature planning for existing codebases.**
|
|
4
|
+
|
|
5
|
+
A Claude Code extension that analyzes your codebase and generates structured documentation. Understand any codebase before planning new features.
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npx specdacular
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## What It Does
|
|
14
|
+
|
|
15
|
+
Specdacular spawns 4 parallel AI agents to analyze your codebase and generate 7 structured documents:
|
|
16
|
+
|
|
17
|
+
| Document | What It Answers |
|
|
18
|
+
|----------|-----------------|
|
|
19
|
+
| `STACK.md` | What languages, frameworks, dependencies? |
|
|
20
|
+
| `ARCHITECTURE.md` | What patterns? How does data flow? |
|
|
21
|
+
| `STRUCTURE.md` | Where do files go? How is it organized? |
|
|
22
|
+
| `CONVENTIONS.md` | How should code be written? Naming? Style? |
|
|
23
|
+
| `TESTING.md` | How are tests structured? What to mock? |
|
|
24
|
+
| `INTEGRATIONS.md` | What external services (DB, APIs, auth)? |
|
|
25
|
+
| `CONCERNS.md` | What's broken? Tech debt? Risks? |
|
|
26
|
+
|
|
27
|
+
Output goes to `.specd/codebase/` in your project.
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## Installation
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
npx specdacular
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Choose:
|
|
38
|
+
- **Global** (`~/.claude/`) - Available in all projects
|
|
39
|
+
- **Local** (`./.claude/`) - This project only
|
|
40
|
+
|
|
41
|
+
### Verify Installation
|
|
42
|
+
|
|
43
|
+
In Claude Code:
|
|
44
|
+
```
|
|
45
|
+
/specd:help
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
50
|
+
## Usage
|
|
51
|
+
|
|
52
|
+
### Map Your Codebase
|
|
53
|
+
|
|
54
|
+
```
|
|
55
|
+
/specd:map-codebase
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
This:
|
|
59
|
+
1. Creates `.specd/codebase/` directory
|
|
60
|
+
2. Spawns 4 parallel agents (tech, architecture, quality, concerns)
|
|
61
|
+
3. Each agent explores and writes documents directly
|
|
62
|
+
4. Commits the codebase map
|
|
63
|
+
|
|
64
|
+
### Review Generated Docs
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
cat .specd/codebase/STACK.md
|
|
68
|
+
cat .specd/codebase/ARCHITECTURE.md
|
|
69
|
+
# etc.
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
---
|
|
73
|
+
|
|
74
|
+
## Commands
|
|
75
|
+
|
|
76
|
+
| Command | Description |
|
|
77
|
+
|---------|-------------|
|
|
78
|
+
| `/specd:map-codebase` | Analyze codebase and generate documentation |
|
|
79
|
+
| `/specd:help` | Show available commands |
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
## How It Works
|
|
84
|
+
|
|
85
|
+
### Parallel Agents
|
|
86
|
+
|
|
87
|
+
Instead of one agent doing everything, Specdacular spawns 4 specialized agents that run simultaneously:
|
|
88
|
+
|
|
89
|
+
```
|
|
90
|
+
┌─────────────────────────────────────────────────────────┐
|
|
91
|
+
│ /specd:map-codebase │
|
|
92
|
+
└─────────────────────────────────────────────────────────┘
|
|
93
|
+
│
|
|
94
|
+
┌───────────────┼───────────────┐
|
|
95
|
+
▼ ▼ ▼ ▼
|
|
96
|
+
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
|
|
97
|
+
│ Tech │ │ Arch │ │ Quality │ │ Concerns │
|
|
98
|
+
│ Agent │ │ Agent │ │ Agent │ │ Agent │
|
|
99
|
+
└──────────┘ └──────────┘ └──────────┘ └──────────┘
|
|
100
|
+
│ │ │ │
|
|
101
|
+
▼ ▼ ▼ ▼
|
|
102
|
+
STACK.md ARCH.md CONV.md CONCERNS.md
|
|
103
|
+
INTEG.md STRUCT.md TESTING.md
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
**Benefits:**
|
|
107
|
+
- Fresh 200k context per agent (no token pollution)
|
|
108
|
+
- Faster execution (parallel, not sequential)
|
|
109
|
+
- Agents write directly to files (minimal context transfer)
|
|
110
|
+
|
|
111
|
+
---
|
|
112
|
+
|
|
113
|
+
## Updating
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
npx specdacular@latest
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
## Uninstalling
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
npx specdacular --global --uninstall
|
|
123
|
+
# or
|
|
124
|
+
npx specdacular --local --uninstall
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
---
|
|
128
|
+
|
|
129
|
+
## Project Structure
|
|
130
|
+
|
|
131
|
+
After running `/specd:map-codebase`:
|
|
132
|
+
|
|
133
|
+
```
|
|
134
|
+
your-project/
|
|
135
|
+
├── .specd/
|
|
136
|
+
│ └── codebase/
|
|
137
|
+
│ ├── STACK.md
|
|
138
|
+
│ ├── ARCHITECTURE.md
|
|
139
|
+
│ ├── STRUCTURE.md
|
|
140
|
+
│ ├── CONVENTIONS.md
|
|
141
|
+
│ ├── TESTING.md
|
|
142
|
+
│ ├── INTEGRATIONS.md
|
|
143
|
+
│ └── CONCERNS.md
|
|
144
|
+
└── ...
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
---
|
|
148
|
+
|
|
149
|
+
## License
|
|
150
|
+
|
|
151
|
+
MIT
|