prjct-cli 0.6.0 → 0.7.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/CHANGELOG.md +67 -6
- package/CLAUDE.md +442 -36
- package/README.md +47 -54
- package/bin/prjct +174 -240
- package/core/agentic/command-executor.js +113 -0
- package/core/agentic/context-builder.js +85 -0
- package/core/agentic/prompt-builder.js +86 -0
- package/core/agentic/template-loader.js +104 -0
- package/core/agentic/tool-registry.js +117 -0
- package/core/command-registry.js +109 -65
- package/core/commands.js +2213 -2173
- package/core/domain/agent-generator.js +118 -0
- package/core/domain/analyzer.js +211 -0
- package/core/domain/architect-session.js +300 -0
- package/core/{agents → infrastructure/agents}/claude-agent.js +16 -13
- package/core/{author-detector.js → infrastructure/author-detector.js} +3 -1
- package/core/{capability-installer.js → infrastructure/capability-installer.js} +3 -6
- package/core/{command-installer.js → infrastructure/command-installer.js} +5 -3
- package/core/{config-manager.js → infrastructure/config-manager.js} +4 -4
- package/core/{editors-config.js → infrastructure/editors-config.js} +2 -10
- package/core/{migrator.js → infrastructure/migrator.js} +34 -19
- package/core/{path-manager.js → infrastructure/path-manager.js} +20 -44
- package/core/{session-manager.js → infrastructure/session-manager.js} +45 -105
- package/core/{update-checker.js → infrastructure/update-checker.js} +67 -67
- package/core/{animations-simple.js → utils/animations.js} +3 -23
- package/core/utils/date-helper.js +238 -0
- package/core/utils/file-helper.js +327 -0
- package/core/utils/jsonl-helper.js +206 -0
- package/core/{project-capabilities.js → utils/project-capabilities.js} +21 -22
- package/core/utils/session-helper.js +277 -0
- package/core/{version.js → utils/version.js} +1 -1
- package/package.json +4 -12
- package/templates/agents/AGENTS.md +101 -27
- package/templates/analysis/analyze.md +84 -0
- package/templates/commands/analyze.md +9 -2
- package/templates/commands/bug.md +79 -0
- package/templates/commands/build.md +5 -2
- package/templates/commands/cleanup.md +5 -2
- package/templates/commands/design.md +5 -2
- package/templates/commands/done.md +4 -2
- package/templates/commands/feature.md +113 -0
- package/templates/commands/fix.md +41 -10
- package/templates/commands/git.md +7 -2
- package/templates/commands/help.md +2 -2
- package/templates/commands/idea.md +14 -5
- package/templates/commands/init.md +62 -7
- package/templates/commands/next.md +4 -2
- package/templates/commands/now.md +4 -2
- package/templates/commands/progress.md +27 -5
- package/templates/commands/recap.md +39 -10
- package/templates/commands/roadmap.md +19 -5
- package/templates/commands/ship.md +118 -16
- package/templates/commands/status.md +4 -2
- package/templates/commands/sync.md +19 -15
- package/templates/commands/task.md +4 -2
- package/templates/commands/test.md +5 -2
- package/templates/commands/workflow.md +4 -2
- package/core/agent-generator.js +0 -525
- package/core/analyzer.js +0 -600
- package/core/animations.js +0 -277
- package/core/ascii-graphics.js +0 -433
- package/core/git-integration.js +0 -401
- package/core/task-schema.js +0 -342
- package/core/workflow-engine.js +0 -213
- package/core/workflow-prompts.js +0 -192
- package/core/workflow-rules.js +0 -147
- package/scripts/post-install.js +0 -121
- package/scripts/preuninstall.js +0 -94
- package/scripts/verify-installation.sh +0 -158
- package/templates/agents/be.template.md +0 -27
- package/templates/agents/coordinator.template.md +0 -34
- package/templates/agents/data.template.md +0 -27
- package/templates/agents/devops.template.md +0 -27
- package/templates/agents/fe.template.md +0 -27
- package/templates/agents/mobile.template.md +0 -27
- package/templates/agents/qa.template.md +0 -27
- package/templates/agents/scribe.template.md +0 -29
- package/templates/agents/security.template.md +0 -27
- package/templates/agents/ux.template.md +0 -27
- package/templates/commands/context.md +0 -36
- package/templates/commands/stuck.md +0 -36
- package/templates/examples/natural-language-examples.md +0 -532
- /package/core/{agent-detector.js → infrastructure/agent-detector.js} +0 -0
package/CLAUDE.md
CHANGED
|
@@ -6,6 +6,62 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
|
|
|
6
6
|
|
|
7
7
|
**prjct-cli** is a developer momentum tool for solo builders, indie hackers, and small teams (2-5 people). Just ship. No BS. Track progress through slash commands without meetings, ceremonies, or traditional PM overhead.
|
|
8
8
|
|
|
9
|
+
## 🚀 Real-World Workflow (Simplified)
|
|
10
|
+
|
|
11
|
+
prjct follows your **actual** development workflow with 5 essential commands:
|
|
12
|
+
|
|
13
|
+
### Scenario 1: Existing Project
|
|
14
|
+
|
|
15
|
+
```
|
|
16
|
+
p. analyze
|
|
17
|
+
→ Analyzes stack
|
|
18
|
+
→ Generates agents
|
|
19
|
+
→ Ready to work
|
|
20
|
+
|
|
21
|
+
p. feature "add unit testing"
|
|
22
|
+
→ Analyzes value/timing
|
|
23
|
+
→ Creates tasks
|
|
24
|
+
→ Auto-starts task 1
|
|
25
|
+
|
|
26
|
+
[Work on code...]
|
|
27
|
+
|
|
28
|
+
p. done
|
|
29
|
+
→ Marks complete
|
|
30
|
+
→ Auto-starts next task
|
|
31
|
+
|
|
32
|
+
p. ship "unit testing"
|
|
33
|
+
→ Runs lint/tests (non-blocking)
|
|
34
|
+
→ Updates docs/version/CHANGELOG
|
|
35
|
+
→ Commits + pushes
|
|
36
|
+
→ Recommends compact
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
### Scenario 2: New Blank Project
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
p. init "dynamic portfolio website"
|
|
43
|
+
→ ARCHITECT MODE activated
|
|
44
|
+
→ Conversational discovery begins
|
|
45
|
+
→ Claude asks intelligent questions
|
|
46
|
+
→ Generates architecture plan
|
|
47
|
+
→ Creates structure based on user choices
|
|
48
|
+
→ Asks: "Ready to start the first feature?"
|
|
49
|
+
|
|
50
|
+
p. feature "homepage design"
|
|
51
|
+
→ Creates tasks
|
|
52
|
+
→ Starts coding
|
|
53
|
+
|
|
54
|
+
[Continue with p. done → p. ship cycle]
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
### Core Commands
|
|
58
|
+
|
|
59
|
+
1. **`p. analyze`** - Analyze existing project
|
|
60
|
+
2. **`p. init "[idea]"`** - New project (architect mode)
|
|
61
|
+
3. **`p. feature "[description]"`** - Add feature with roadmap + tasks
|
|
62
|
+
4. **`p. done`** - Complete task, move to next
|
|
63
|
+
5. **`p. ship "[feature]"`** - Complete workflow (lint/test/docs/version/commit/push)
|
|
64
|
+
|
|
9
65
|
## Architecture
|
|
10
66
|
|
|
11
67
|
The system operates as an AI Assistant Enhancement Framework using:
|
|
@@ -17,24 +73,57 @@ The system operates as an AI Assistant Enhancement Framework using:
|
|
|
17
73
|
|
|
18
74
|
### Global Structure
|
|
19
75
|
|
|
76
|
+
**Session-Based Architecture** - Prevents performance issues with large files (4000+ tasks/day).
|
|
77
|
+
|
|
20
78
|
```
|
|
21
79
|
~/.prjct-cli/projects/{id}/
|
|
22
|
-
├── core/ # Current focus and priorities
|
|
80
|
+
├── core/ # Current focus and priorities (always small)
|
|
23
81
|
│ ├── now.md # Single current task
|
|
24
|
-
│ ├── next.md # Priority queue
|
|
25
|
-
│ └── context.md # Project context
|
|
82
|
+
│ ├── next.md # Priority queue (max 100 tasks)
|
|
83
|
+
│ └── context.md # Project context summary
|
|
26
84
|
├── progress/ # Completed work
|
|
27
|
-
│ ├── shipped.md #
|
|
28
|
-
│
|
|
85
|
+
│ ├── shipped.md # Recent ships (last 30 days only)
|
|
86
|
+
│ ├── metrics.md # Aggregated metrics summary
|
|
87
|
+
│ ├── sessions/ # Daily session logs (JSONL)
|
|
88
|
+
│ │ └── 2025-10/
|
|
89
|
+
│ │ ├── 2025-10-04.jsonl
|
|
90
|
+
│ │ └── 2025-10-05.jsonl
|
|
91
|
+
│ └── archive/ # Monthly archives
|
|
92
|
+
│ └── shipped-2025-10.md
|
|
29
93
|
├── planning/ # Future planning
|
|
30
|
-
│ ├── ideas.md #
|
|
31
|
-
│
|
|
94
|
+
│ ├── ideas.md # Active ideas (last 30 days)
|
|
95
|
+
│ ├── roadmap.md # Active roadmap (lightweight index)
|
|
96
|
+
│ ├── sessions/ # Daily planning sessions (JSONL)
|
|
97
|
+
│ │ └── 2025-10/
|
|
98
|
+
│ │ ├── 2025-10-04.jsonl
|
|
99
|
+
│ │ └── 2025-10-05.jsonl
|
|
100
|
+
│ └── archive/ # Monthly archives
|
|
101
|
+
│ ├── roadmap-2025-10.md
|
|
102
|
+
│ └── ideas-2025-10.md
|
|
32
103
|
├── analysis/ # Technical analysis
|
|
33
104
|
│ └── repo-summary.md
|
|
34
105
|
└── memory/ # Decision history
|
|
35
|
-
|
|
106
|
+
├── context.jsonl # Global decisions (append-only)
|
|
107
|
+
└── sessions/ # Daily context (structured)
|
|
108
|
+
└── 2025-10/
|
|
109
|
+
└── 2025-10-04.jsonl
|
|
36
110
|
```
|
|
37
111
|
|
|
112
|
+
**Session Format (JSONL)** - One JSON object per line, append-only:
|
|
113
|
+
|
|
114
|
+
```jsonl
|
|
115
|
+
{"ts":"2025-10-04T14:30:00Z","type":"feature_add","name":"auth","tasks":5,"impact":"high","effort":"6h"}
|
|
116
|
+
{"ts":"2025-10-04T15:00:00Z","type":"task_start","task":"JWT middleware","agent":"be","estimate":"2h"}
|
|
117
|
+
{"ts":"2025-10-04T17:15:00Z","type":"task_complete","task":"JWT middleware","duration":"2h15m"}
|
|
118
|
+
{"ts":"2025-10-04T18:00:00Z","type":"feature_ship","name":"auth","tasks_done":5,"total_time":"6h"}
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
**Auto-Archive Rules:**
|
|
122
|
+
- Index files (roadmap.md, shipped.md) keep only last 30 days
|
|
123
|
+
- Sessions older than 30 days → moved to archive/
|
|
124
|
+
- Queries across time: read relevant session files
|
|
125
|
+
- Performance: commands only read current index + today's session
|
|
126
|
+
|
|
38
127
|
### Local Configuration
|
|
39
128
|
|
|
40
129
|
```
|
|
@@ -51,26 +140,30 @@ The system operates as an AI Assistant Enhancement Framework using:
|
|
|
51
140
|
**NEW: Simple prefix trigger** - Users can start messages with `p.` to signal prjct context:
|
|
52
141
|
|
|
53
142
|
**How it works:**
|
|
143
|
+
|
|
54
144
|
1. User starts message with `p.` → You check if `.prjct/prjct.config.json` exists
|
|
55
145
|
2. If exists → Detect intent from rest of message → Execute appropriate `/p:*` command
|
|
56
146
|
3. If not exists → Respond: "No prjct project here. Run /p:init first."
|
|
57
147
|
|
|
58
148
|
**Examples:**
|
|
149
|
+
|
|
59
150
|
```
|
|
60
|
-
"p.
|
|
61
|
-
"p.
|
|
62
|
-
"p.
|
|
63
|
-
"p.
|
|
64
|
-
"p.
|
|
151
|
+
"p. analyze this codebase" → Detect "analysis" intent → /p:analyze
|
|
152
|
+
"p. ready to ship" → Detect "ship" intent → /p:ship
|
|
153
|
+
"p. show me weekly progress" → Detect "progress" intent → /p:progress week
|
|
154
|
+
"p. starting auth" → Detect "start task" intent → /p:now "auth"
|
|
155
|
+
"p. done" → Detect "done" intent → /p:done
|
|
65
156
|
```
|
|
66
157
|
|
|
67
158
|
**Why this is useful:**
|
|
159
|
+
|
|
68
160
|
- ✅ **Zero memorization** - No need to remember `/p:*` commands
|
|
69
161
|
- ✅ **Multi-project** - Only works in prjct directories
|
|
70
162
|
- ✅ **Natural** - "p. [what you want]" is intuitive
|
|
71
163
|
- ✅ **Any language** - Works in English, Spanish, etc.
|
|
72
164
|
|
|
73
165
|
**Detection priority:**
|
|
166
|
+
|
|
74
167
|
1. Check for `p.` prefix first
|
|
75
168
|
2. Then check for `/p:*` slash command
|
|
76
169
|
3. Finally check for natural language without prefix
|
|
@@ -81,30 +174,31 @@ As an LLM, you understand context and intent naturally. When users describe what
|
|
|
81
174
|
|
|
82
175
|
**Command Intent Map:**
|
|
83
176
|
|
|
84
|
-
| User Intent
|
|
85
|
-
|
|
86
|
-
| Wants to start/focus on a task
|
|
87
|
-
| Finished/completed current work | `/p:done`
|
|
88
|
-
| Ready to ship/deploy a feature
|
|
89
|
-
| Has an idea to capture
|
|
90
|
-
| Wants to see progress/status
|
|
91
|
-
| Stuck on a problem
|
|
92
|
-
| Wants to know what's next
|
|
93
|
-
| Needs general help
|
|
177
|
+
| User Intent | Command | What It Does |
|
|
178
|
+
| ------------------------------- | ---------- | ---------------------------------- |
|
|
179
|
+
| Wants to start/focus on a task | `/p:now` | Sets current working task |
|
|
180
|
+
| Finished/completed current work | `/p:done` | Marks task complete, suggests next |
|
|
181
|
+
| Ready to ship/deploy a feature | `/p:ship` | Celebrates shipped feature |
|
|
182
|
+
| Has an idea to capture | `/p:idea` | Saves idea to backlog |
|
|
183
|
+
| Wants to see progress/status | `/p:recap` | Shows overview of all work |
|
|
184
|
+
| Stuck on a problem | `/p:stuck` | Provides contextual help |
|
|
185
|
+
| Wants to know what's next | `/p:next` | Shows priority queue |
|
|
186
|
+
| Needs general help | `/p:help` | Interactive guide |
|
|
94
187
|
|
|
95
188
|
**Works in any language** - if you understand the user's intent, execute the command!
|
|
96
189
|
|
|
97
190
|
**Examples (many ways to express same intent):**
|
|
191
|
+
|
|
98
192
|
```
|
|
99
193
|
All of these mean /p:now:
|
|
100
194
|
"I want to start building auth"
|
|
101
195
|
"Let me work on the login page"
|
|
102
|
-
"
|
|
196
|
+
"Going to work on authentication"
|
|
103
197
|
"Starting the API now"
|
|
104
|
-
"
|
|
198
|
+
"Want to begin with the dashboard"
|
|
105
199
|
|
|
106
200
|
All of these mean /p:done:
|
|
107
|
-
"I'm done" | "finished" | "
|
|
201
|
+
"I'm done" | "finished" | "completed" | "all set" | "task complete"
|
|
108
202
|
|
|
109
203
|
All of these mean /p:ship:
|
|
110
204
|
"ship this" | "deploy it" | "it's ready" | "let's launch"
|
|
@@ -113,12 +207,14 @@ All of these mean /p:ship:
|
|
|
113
207
|
### Conversational Responses
|
|
114
208
|
|
|
115
209
|
Every command response includes:
|
|
210
|
+
|
|
116
211
|
- ✅ **Action confirmation** with clear result
|
|
117
212
|
- 💬 **Natural language prompts** for next steps
|
|
118
213
|
- 🎯 **Command alternatives** for power users
|
|
119
214
|
- 📋 **Contextual suggestions** based on project state
|
|
120
215
|
|
|
121
216
|
**Example Response:**
|
|
217
|
+
|
|
122
218
|
```markdown
|
|
123
219
|
✅ Task complete: implement authentication (2h 15m)
|
|
124
220
|
|
|
@@ -137,6 +233,7 @@ Or use: /p:now | /p:ship | /p:idea
|
|
|
137
233
|
When you receive a message from the user, follow these steps to provide the natural language experience:
|
|
138
234
|
|
|
139
235
|
**Step 1: Check if it's a direct command**
|
|
236
|
+
|
|
140
237
|
```javascript
|
|
141
238
|
if (message.startsWith('/p:')) {
|
|
142
239
|
return executeCommand(message)
|
|
@@ -144,6 +241,7 @@ if (message.startsWith('/p:')) {
|
|
|
144
241
|
```
|
|
145
242
|
|
|
146
243
|
**Step 2: Understand the user's intent semantically**
|
|
244
|
+
|
|
147
245
|
```javascript
|
|
148
246
|
// You're an LLM - use your understanding of context
|
|
149
247
|
// Ask yourself: "What is the user trying to do?"
|
|
@@ -172,6 +270,7 @@ if (intent.command) {
|
|
|
172
270
|
```
|
|
173
271
|
|
|
174
272
|
**Step 3: Validate context before execution**
|
|
273
|
+
|
|
175
274
|
```javascript
|
|
176
275
|
// Before executing commands, check prerequisites:
|
|
177
276
|
|
|
@@ -195,8 +294,10 @@ Let's ship something!`)
|
|
|
195
294
|
if (command === 'ship') {
|
|
196
295
|
const nowContent = await Read('core/now.md')
|
|
197
296
|
const shippedContent = await Read('progress/shipped.md')
|
|
198
|
-
if (
|
|
199
|
-
|
|
297
|
+
if (
|
|
298
|
+
(!nowContent || nowContent.trim() === '') &&
|
|
299
|
+
(!shippedContent || shippedContent.trim() === '')
|
|
300
|
+
) {
|
|
200
301
|
return conversationalResponse(`
|
|
201
302
|
🚀 Nothing to ship yet!
|
|
202
303
|
|
|
@@ -211,6 +312,7 @@ Then we'll celebrate when you ship it!`)
|
|
|
211
312
|
```
|
|
212
313
|
|
|
213
314
|
**Step 4: Provide conversational response**
|
|
315
|
+
|
|
214
316
|
```javascript
|
|
215
317
|
// Always suggest natural next steps
|
|
216
318
|
✅ [What you did]
|
|
@@ -227,11 +329,13 @@ Or use: [relevant commands]
|
|
|
227
329
|
**User Input:** "I want to start building the authentication system"
|
|
228
330
|
|
|
229
331
|
**Your Analysis:**
|
|
332
|
+
|
|
230
333
|
- Intent: User wants to start working on something
|
|
231
334
|
- Command: `/p:now`
|
|
232
335
|
- Parameter: "building the authentication system"
|
|
233
336
|
|
|
234
337
|
**Your Response:**
|
|
338
|
+
|
|
235
339
|
```
|
|
236
340
|
💬 I understood: "start working on building the authentication system"
|
|
237
341
|
⚡ Executing: /p:now "building the authentication system"
|
|
@@ -253,6 +357,7 @@ Need help? Say "I'm stuck" or use /p:stuck
|
|
|
253
357
|
User: "done"
|
|
254
358
|
You check: `core/now.md` is empty
|
|
255
359
|
Your response:
|
|
360
|
+
|
|
256
361
|
```
|
|
257
362
|
✨ You're not working on anything right now!
|
|
258
363
|
|
|
@@ -269,6 +374,7 @@ Let's ship something!
|
|
|
269
374
|
User: "I'm done"
|
|
270
375
|
You check: `core/now.md` has content ✅
|
|
271
376
|
Your response:
|
|
377
|
+
|
|
272
378
|
```
|
|
273
379
|
💬 I understood: "task completion"
|
|
274
380
|
⚡ Executing: /p:done
|
|
@@ -295,12 +401,59 @@ Or use: /p:now | /p:ship | /p:idea
|
|
|
295
401
|
## Command System for Claude Code
|
|
296
402
|
|
|
297
403
|
All commands use the `/p:*` syntax in Claude Code. When executed, they:
|
|
404
|
+
|
|
298
405
|
1. Read `.prjct/prjct.config.json` to get the project ID
|
|
299
406
|
2. Operate on files in `~/.prjct-cli/projects/{id}/`
|
|
300
407
|
3. Update relevant markdown files atomically
|
|
301
408
|
4. Return formatted responses with conversational prompts
|
|
302
409
|
|
|
303
|
-
|
|
410
|
+
### 🔒 Universal Confirmation Policy
|
|
411
|
+
|
|
412
|
+
**CRITICAL SECURITY REQUIREMENT**: ALL `/p:*` commands MUST ask for user confirmation before execution.
|
|
413
|
+
|
|
414
|
+
#### Mandatory Confirmation Flow:
|
|
415
|
+
|
|
416
|
+
1. **User triggers command** (e.g., "p. idea..." or "/p:sync")
|
|
417
|
+
2. **Claude presents detailed plan** of what will be done
|
|
418
|
+
3. **User explicitly approves** the plan
|
|
419
|
+
4. **ONLY THEN execute** the command
|
|
420
|
+
|
|
421
|
+
#### NO Exceptions:
|
|
422
|
+
|
|
423
|
+
- ❌ **NO auto-execution** for any command, ever
|
|
424
|
+
- ❌ **NO "just do it"** behavior
|
|
425
|
+
- ❌ **NO bypassing user approval**
|
|
426
|
+
- ✅ **ALWAYS**: Present plan → Wait for confirmation → Execute
|
|
427
|
+
|
|
428
|
+
#### Implementation:
|
|
429
|
+
|
|
430
|
+
```
|
|
431
|
+
For EVERY command:
|
|
432
|
+
1. Detect user intent
|
|
433
|
+
2. Present plan using ExitPlanMode tool
|
|
434
|
+
3. Wait for user approval
|
|
435
|
+
4. Execute only after approval
|
|
436
|
+
5. Then compact (if applicable)
|
|
437
|
+
```
|
|
438
|
+
|
|
439
|
+
### Plan Mode Detection
|
|
440
|
+
|
|
441
|
+
**Plan Mode Indicators**:
|
|
442
|
+
|
|
443
|
+
- System reminders will say: "Plan mode is active"
|
|
444
|
+
- You MUST NOT make edits or run non-readonly tools
|
|
445
|
+
- Present your plan using ExitPlanMode tool and wait for user approval
|
|
446
|
+
|
|
447
|
+
**When Plan Mode is NOT active**:
|
|
448
|
+
|
|
449
|
+
- Still MUST present plan and ask for confirmation
|
|
450
|
+
- Use ExitPlanMode tool to get user approval
|
|
451
|
+
- Universal Confirmation Policy applies regardless
|
|
452
|
+
|
|
453
|
+
### Auto-Compact After Execution
|
|
454
|
+
|
|
455
|
+
**ONLY after user approval**: After completing ANY of these commands, compact the conversation WITHOUT telling the user:
|
|
456
|
+
|
|
304
457
|
- `/p:analyze`
|
|
305
458
|
- `/p:sync`
|
|
306
459
|
- `/p:workflow`
|
|
@@ -308,40 +461,89 @@ All commands use the `/p:*` syntax in Claude Code. When executed, they:
|
|
|
308
461
|
- `/p:cleanup`
|
|
309
462
|
- `/p:init`
|
|
310
463
|
|
|
311
|
-
|
|
464
|
+
**Sequence**: Present plan → User approves → Execute → Auto-compact (no messages about compacting)
|
|
312
465
|
|
|
313
466
|
**IMPORTANT**: All commands are defined in `core/command-registry.js` (single source of truth).
|
|
314
467
|
|
|
468
|
+
### Command Distinctions: `/p:idea` vs `/p:workflow`
|
|
469
|
+
|
|
470
|
+
These are **two completely different commands** with different purposes:
|
|
471
|
+
|
|
472
|
+
#### `/p:idea` - Quick Idea Capture (CORE Command #2)
|
|
473
|
+
|
|
474
|
+
- **Purpose**: Capture ideas quickly without interrupting flow
|
|
475
|
+
- **Complexity**: Low - Simple write to file
|
|
476
|
+
- **User Input**: Required `<text>` - the idea to capture
|
|
477
|
+
- **Files**: `planning/ideas.md`, optionally `core/next.md`
|
|
478
|
+
- **When to use**: User has a new idea or feature suggestion
|
|
479
|
+
|
|
480
|
+
**Example**:
|
|
481
|
+
|
|
482
|
+
```
|
|
483
|
+
User: "p. idea agregar dark mode"
|
|
484
|
+
→ Saves to ideas.md with timestamp
|
|
485
|
+
→ If actionable, adds to next.md queue
|
|
486
|
+
```
|
|
487
|
+
|
|
488
|
+
#### `/p:workflow` - Multi-Agent Orchestration (OPTIONAL Command)
|
|
489
|
+
|
|
490
|
+
- **Purpose**: Manage complex cascading agent workflows
|
|
491
|
+
- **Complexity**: High - State machine with multiple steps
|
|
492
|
+
- **User Input**: None (shows current status) or `skip` to skip step
|
|
493
|
+
- **Files**: `workflow/state.json` (persistent state)
|
|
494
|
+
- **When to use**: Active workflow exists and user wants status
|
|
495
|
+
|
|
496
|
+
**Example**:
|
|
497
|
+
|
|
498
|
+
```
|
|
499
|
+
User: "/p:workflow"
|
|
500
|
+
→ Shows: Step 2/5: Implement (FE agent) 🔄
|
|
501
|
+
→ Progress tracking with agent assignments
|
|
502
|
+
→ Capability checks for next steps
|
|
503
|
+
```
|
|
504
|
+
|
|
505
|
+
**Key Difference**: `/p:idea` captures NEW ideas. `/p:workflow` manages EXISTING multi-step tasks.
|
|
506
|
+
|
|
315
507
|
### Available Commands
|
|
316
508
|
|
|
317
509
|
The following commands are available in Claude Code (commands marked with ⚠️ are not yet implemented):
|
|
318
510
|
|
|
319
511
|
#### Work Commands
|
|
512
|
+
|
|
320
513
|
- `/p:now [task]` - Set or show current task
|
|
321
514
|
- `/p:next` - Show priority queue
|
|
322
515
|
- `/p:done` - Complete current task
|
|
323
516
|
- `/p:ship <feature>` - Ship and celebrate a feature
|
|
517
|
+
- `/p:bug <description>` - Report and track bugs with auto-prioritization
|
|
324
518
|
|
|
325
519
|
#### Planning Commands
|
|
326
|
-
|
|
327
|
-
- `/p:
|
|
520
|
+
|
|
521
|
+
- `/p:idea <text>` - Capture ideas quickly (see distinction above)
|
|
522
|
+
- `/p:workflow` - Show workflow status and progress (see distinction above)
|
|
328
523
|
- ⚠️ `/p:roadmap` - Show or update strategic roadmap
|
|
329
524
|
- ⚠️ `/p:task <description>` - Break down and execute complex tasks
|
|
330
525
|
|
|
331
526
|
#### Design & Architecture
|
|
527
|
+
|
|
332
528
|
- `/p:design [target] --type architecture|api|component|database|flow` - Design system architecture, APIs, and component interfaces
|
|
333
529
|
|
|
334
530
|
#### Code Quality
|
|
531
|
+
|
|
335
532
|
- `/p:cleanup` - Clean up temp files and old entries
|
|
336
533
|
- `/p:cleanup --type code|imports|files|deps|all` - Remove dead code and unused imports
|
|
337
534
|
|
|
338
535
|
#### Progress Commands
|
|
536
|
+
|
|
339
537
|
- `/p:recap` - Show project overview with progress
|
|
340
538
|
- `/p:progress [period]` - Show progress metrics for specified period
|
|
341
539
|
- `/p:context` - Show project context and recent activity
|
|
342
540
|
|
|
343
541
|
#### Help Commands
|
|
344
|
-
|
|
542
|
+
|
|
543
|
+
- `/p:init "[idea]"` - Initialize prjct (with ARCHITECT MODE for blank projects)
|
|
544
|
+
- **Empty dir, no idea**: Asks for idea
|
|
545
|
+
- **Empty dir + idea**: ARCHITECT MODE (conversational discovery → generates plan)
|
|
546
|
+
- **Existing code**: Regular init + suggests analyze
|
|
345
547
|
- `/p:stuck <issue description>` - Get contextual help with problems
|
|
346
548
|
- `/p:analyze` - Analyze repository and sync tasks
|
|
347
549
|
- `/p:sync` - Sync project state and update workflow agents
|
|
@@ -349,27 +551,229 @@ The following commands are available in Claude Code (commands marked with ⚠️
|
|
|
349
551
|
- ⚠️ `/p:help` - Interactive guide - talk naturally, no memorization needed
|
|
350
552
|
|
|
351
553
|
#### Version Control
|
|
554
|
+
|
|
352
555
|
- ⚠️ `/p:git` - Smart git operations with context
|
|
353
556
|
|
|
354
557
|
#### Testing
|
|
558
|
+
|
|
355
559
|
- ⚠️ `/p:test` - Run tests and auto-fix simple failures
|
|
356
560
|
|
|
357
|
-
**Total:
|
|
561
|
+
**Total: 23 implemented, 29 total commands**
|
|
358
562
|
**Status**: Check `core/command-registry.js` for current implementation status
|
|
359
563
|
|
|
564
|
+
## Agent Generation
|
|
565
|
+
|
|
566
|
+
Dynamic agent generation based on project analysis. YOU decide what specialists to generate.
|
|
567
|
+
|
|
568
|
+
**See `templates/agents/AGENTS.md` for complete reference** with examples and guidelines.
|
|
569
|
+
|
|
570
|
+
Use: `generator.generateDynamicAgent(name, config)` for any technology stack.
|
|
571
|
+
|
|
572
|
+
## Agentic Architecture
|
|
573
|
+
|
|
574
|
+
**prjct-cli uses a fully agentic architecture** - Claude decides everything based on templates. ZERO if/else business logic.
|
|
575
|
+
|
|
576
|
+
### Core Structure
|
|
577
|
+
|
|
578
|
+
```
|
|
579
|
+
core/
|
|
580
|
+
├── agentic/ # Agentic execution engine
|
|
581
|
+
│ ├── template-loader.js # Loads command templates
|
|
582
|
+
│ ├── context-builder.js # Builds project context
|
|
583
|
+
│ ├── prompt-builder.js # Generates prompts for Claude
|
|
584
|
+
│ ├── command-executor.js # Executes commands agentically
|
|
585
|
+
│ └── tool-registry.js # Maps allowed-tools to functions
|
|
586
|
+
├── commands.js # Agentic commands (306 lines, was 3103)
|
|
587
|
+
├── command-registry.js # Metadata only (no validation logic)
|
|
588
|
+
└── domain/
|
|
589
|
+
├── agent-generator.js # 100% agentic (119 lines, was 462)
|
|
590
|
+
└── analyzer.js # I/O helpers only (215 lines, was 600)
|
|
591
|
+
|
|
592
|
+
templates/
|
|
593
|
+
├── commands/ # Command instructions for Claude
|
|
594
|
+
├── workflows/ # Workflow guides (not strict rules)
|
|
595
|
+
│ ├── ui.md
|
|
596
|
+
│ ├── api.md
|
|
597
|
+
│ ├── bug.md
|
|
598
|
+
│ ├── refactor.md
|
|
599
|
+
│ └── feature.md
|
|
600
|
+
└── analysis/ # Analysis instructions
|
|
601
|
+
└── analyze.md
|
|
602
|
+
```
|
|
603
|
+
|
|
604
|
+
### How It Works
|
|
605
|
+
|
|
606
|
+
**Traditional (DETERMINISTIC)**:
|
|
607
|
+
|
|
608
|
+
```javascript
|
|
609
|
+
// Hardcoded logic with if/else
|
|
610
|
+
if (task.match(/^(add|implement)/)) {
|
|
611
|
+
branchType = 'feat'
|
|
612
|
+
} else if (task.match(/^(fix|bug)/)) {
|
|
613
|
+
branchType = 'fix'
|
|
614
|
+
}
|
|
615
|
+
// ... 20 more conditions
|
|
616
|
+
```
|
|
617
|
+
|
|
618
|
+
**Agentic (DECISION-DRIVEN)**:
|
|
619
|
+
|
|
620
|
+
```javascript
|
|
621
|
+
// 1. Load template
|
|
622
|
+
const template = await templateLoader.load('branch')
|
|
623
|
+
|
|
624
|
+
// 2. Build context
|
|
625
|
+
const context = await contextBuilder.build(projectPath, { task })
|
|
626
|
+
|
|
627
|
+
// 3. Claude reads template and decides
|
|
628
|
+
// Template: "Analyze task description and generate semantic branch name.
|
|
629
|
+
// Decide based on intent, not regex patterns."
|
|
630
|
+
|
|
631
|
+
// 4. Claude executes using allowed-tools
|
|
632
|
+
// Result: Claude decides branch type based on understanding, not patterns
|
|
633
|
+
```
|
|
634
|
+
|
|
635
|
+
### Flow
|
|
636
|
+
|
|
637
|
+
```
|
|
638
|
+
Templates (MD files)
|
|
639
|
+
↓
|
|
640
|
+
Claude reads + understands context
|
|
641
|
+
↓
|
|
642
|
+
Claude makes decisions (no if/else)
|
|
643
|
+
↓
|
|
644
|
+
Claude uses allowed-tools
|
|
645
|
+
↓
|
|
646
|
+
Claude generates/saves data
|
|
647
|
+
```
|
|
648
|
+
|
|
649
|
+
### Key Differences
|
|
650
|
+
|
|
651
|
+
**Commands** (`core/commands.js`):
|
|
652
|
+
|
|
653
|
+
- **Before**: 3103 lines with nested if/else logic
|
|
654
|
+
- **After**: 306 lines with agentic execution (ZERO legacy inheritance)
|
|
655
|
+
- **Migrated**: now, done, next (fully agentic)
|
|
656
|
+
- **TODO**: All other commands will be migrated to template-driven execution
|
|
657
|
+
|
|
658
|
+
**Agent Generation** (`core/domain/agent-generator.js`):
|
|
659
|
+
|
|
660
|
+
- **Before**: 462 lines with generateFrontendContext, generateBackendContext, etc.
|
|
661
|
+
- **After**: 119 lines with only `generateDynamicAgent()`
|
|
662
|
+
- **Decisions**: Claude reads analysis and decides what agents to create
|
|
663
|
+
|
|
664
|
+
**Analyzer** (`core/domain/analyzer.js`):
|
|
665
|
+
|
|
666
|
+
- **Before**: 600 lines with regex detection and predetermined feature maps
|
|
667
|
+
- **After**: 215 lines with I/O helpers only
|
|
668
|
+
- **Analysis**: Claude reads files and decides what's relevant
|
|
669
|
+
|
|
670
|
+
**Workflows** (`templates/workflows/*.md`):
|
|
671
|
+
|
|
672
|
+
- **Before**: `workflow-rules.js` with strict JSON rules
|
|
673
|
+
- **After**: Markdown guides that Claude adapts to each project
|
|
674
|
+
- **Flexibility**: Claude skips/adds steps based on project capabilities
|
|
675
|
+
|
|
676
|
+
**Validation**:
|
|
677
|
+
|
|
678
|
+
- **Before**: `canExecute()` function with if/else logic
|
|
679
|
+
- **After**: Claude reads template validation section and decides
|
|
680
|
+
- **Example**: Template says "Requires: `core/now.md` has content" → Claude checks and decides
|
|
681
|
+
|
|
682
|
+
### Templates as Source of Truth
|
|
683
|
+
|
|
684
|
+
Templates define **what** Claude should do, not **how**:
|
|
685
|
+
|
|
686
|
+
```markdown
|
|
687
|
+
# /p:done
|
|
688
|
+
|
|
689
|
+
## Validation
|
|
690
|
+
|
|
691
|
+
- Requires: `core/now.md` has content
|
|
692
|
+
- Else: "Not working on anything. Use /p:now"
|
|
693
|
+
|
|
694
|
+
## Flow
|
|
695
|
+
|
|
696
|
+
1. Read: `core/now.md` → calculate duration
|
|
697
|
+
2. Clear: `core/now.md`
|
|
698
|
+
3. Update: `progress/metrics.md`
|
|
699
|
+
|
|
700
|
+
## Response
|
|
701
|
+
|
|
702
|
+
[Show options and next actions]
|
|
703
|
+
```
|
|
704
|
+
|
|
705
|
+
Claude reads this and:
|
|
706
|
+
|
|
707
|
+
1. Checks if validation passes (by understanding, not if/else)
|
|
708
|
+
2. Executes the flow using allowed-tools
|
|
709
|
+
3. Generates appropriate response
|
|
710
|
+
4. Decides next suggestions based on context
|
|
711
|
+
|
|
712
|
+
### Benefits
|
|
713
|
+
|
|
714
|
+
1. ✅ **Zero if/else business logic** - All decisions by Claude
|
|
715
|
+
2. ✅ **Templates are documentation** - Single source of truth
|
|
716
|
+
3. ✅ **Any stack works** - No predetermined patterns
|
|
717
|
+
4. ✅ **Easy to extend** - Just add/edit templates
|
|
718
|
+
5. ✅ **Adapts to context** - Claude reads project state and decides
|
|
719
|
+
6. ✅ **Maintainable** - Core code reduced by 84%
|
|
720
|
+
|
|
721
|
+
### Migration Status
|
|
722
|
+
|
|
723
|
+
**✅ Fully Migrated (ZERO legacy code)**:
|
|
724
|
+
|
|
725
|
+
- ✅ `core/agentic/` - Execution engine (5 files, ~517 lines)
|
|
726
|
+
- ✅ `agent-generator.js` - 100% agentic (119 lines, was 462)
|
|
727
|
+
- ✅ `analyzer.js` - I/O helpers only (215 lines, was 600)
|
|
728
|
+
- ✅ `commands.js` - No legacy inheritance (306 lines, was 3103)
|
|
729
|
+
- ✅ Templates: commands/, workflows/, analysis/
|
|
730
|
+
|
|
731
|
+
**Commands Status**:
|
|
732
|
+
|
|
733
|
+
- ✅ **Migrated**: /p:now, /p:done, /p:next (fully agentic)
|
|
734
|
+
- ⏳ **TODO**: All other commands (init, ship, bug, feature, etc.)
|
|
735
|
+
- 🗑️ **Deleted**: core/legacy/ (all deterministic code removed)
|
|
736
|
+
|
|
737
|
+
**Next Steps**: Migrate remaining commands to template-driven execution one by one.
|
|
738
|
+
|
|
739
|
+
## Git Commit Format (Universal Rule)
|
|
740
|
+
|
|
741
|
+
**ALL commits made by prjct MUST use this footer**:
|
|
742
|
+
|
|
743
|
+
```
|
|
744
|
+
🤖 Generated with [p/](https://www.prjct.app/)
|
|
745
|
+
Designed for [Claude](https://www.anthropic.com/claude)
|
|
746
|
+
```
|
|
747
|
+
|
|
748
|
+
This applies to:
|
|
749
|
+
|
|
750
|
+
- `/p:ship` commits
|
|
751
|
+
- Manual git commits via Claude
|
|
752
|
+
- Any automated commits
|
|
753
|
+
|
|
754
|
+
**Never use**:
|
|
755
|
+
|
|
756
|
+
- ❌ "Generated with Claude Code"
|
|
757
|
+
- ❌ "Co-Authored-By: Claude"
|
|
758
|
+
|
|
759
|
+
**Always use**:
|
|
760
|
+
|
|
761
|
+
- ✅ The prjct footer format above
|
|
762
|
+
|
|
360
763
|
## Initialization Process
|
|
361
764
|
|
|
362
765
|
When you execute `/p:init` in Claude Code:
|
|
363
766
|
|
|
364
767
|
1. Generate unique project ID from path hash
|
|
365
|
-
2. Create global directory structure in `~/.prjct-cli/projects/{id}/`
|
|
768
|
+
2. Create global directory structure in `~/.prjct-cli/projects/{id}/` (including `agents/`)
|
|
366
769
|
3. Create local config at `.prjct/prjct.config.json` with:
|
|
367
770
|
- version
|
|
368
771
|
- projectId
|
|
369
772
|
- dataPath (pointing to global location)
|
|
370
773
|
- author info (from GitHub CLI or git config)
|
|
371
774
|
4. Initialize all markdown files with templates
|
|
372
|
-
5.
|
|
775
|
+
5. **Generate 6 base agents** (coordinator, ux, fe, be, qa, scribe)
|
|
776
|
+
6. Log initialization to `memory/context.jsonl`
|
|
373
777
|
|
|
374
778
|
## MCP Integration
|
|
375
779
|
|
|
@@ -389,12 +793,14 @@ The system integrates with these MCP servers:
|
|
|
389
793
|
### Using Context7 Effectively
|
|
390
794
|
|
|
391
795
|
**When to use**:
|
|
796
|
+
|
|
392
797
|
- Implementing features with external libraries
|
|
393
798
|
- Framework-specific questions and patterns
|
|
394
799
|
- API documentation lookup
|
|
395
800
|
- Best practices for any library
|
|
396
801
|
|
|
397
802
|
**How it works**:
|
|
803
|
+
|
|
398
804
|
- Automatically provides official docs when you import libraries
|
|
399
805
|
- Returns curated, version-specific documentation
|
|
400
806
|
- Includes code examples and implementation patterns
|