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.
Files changed (83) hide show
  1. package/CHANGELOG.md +67 -6
  2. package/CLAUDE.md +442 -36
  3. package/README.md +47 -54
  4. package/bin/prjct +174 -240
  5. package/core/agentic/command-executor.js +113 -0
  6. package/core/agentic/context-builder.js +85 -0
  7. package/core/agentic/prompt-builder.js +86 -0
  8. package/core/agentic/template-loader.js +104 -0
  9. package/core/agentic/tool-registry.js +117 -0
  10. package/core/command-registry.js +109 -65
  11. package/core/commands.js +2213 -2173
  12. package/core/domain/agent-generator.js +118 -0
  13. package/core/domain/analyzer.js +211 -0
  14. package/core/domain/architect-session.js +300 -0
  15. package/core/{agents → infrastructure/agents}/claude-agent.js +16 -13
  16. package/core/{author-detector.js → infrastructure/author-detector.js} +3 -1
  17. package/core/{capability-installer.js → infrastructure/capability-installer.js} +3 -6
  18. package/core/{command-installer.js → infrastructure/command-installer.js} +5 -3
  19. package/core/{config-manager.js → infrastructure/config-manager.js} +4 -4
  20. package/core/{editors-config.js → infrastructure/editors-config.js} +2 -10
  21. package/core/{migrator.js → infrastructure/migrator.js} +34 -19
  22. package/core/{path-manager.js → infrastructure/path-manager.js} +20 -44
  23. package/core/{session-manager.js → infrastructure/session-manager.js} +45 -105
  24. package/core/{update-checker.js → infrastructure/update-checker.js} +67 -67
  25. package/core/{animations-simple.js → utils/animations.js} +3 -23
  26. package/core/utils/date-helper.js +238 -0
  27. package/core/utils/file-helper.js +327 -0
  28. package/core/utils/jsonl-helper.js +206 -0
  29. package/core/{project-capabilities.js → utils/project-capabilities.js} +21 -22
  30. package/core/utils/session-helper.js +277 -0
  31. package/core/{version.js → utils/version.js} +1 -1
  32. package/package.json +4 -12
  33. package/templates/agents/AGENTS.md +101 -27
  34. package/templates/analysis/analyze.md +84 -0
  35. package/templates/commands/analyze.md +9 -2
  36. package/templates/commands/bug.md +79 -0
  37. package/templates/commands/build.md +5 -2
  38. package/templates/commands/cleanup.md +5 -2
  39. package/templates/commands/design.md +5 -2
  40. package/templates/commands/done.md +4 -2
  41. package/templates/commands/feature.md +113 -0
  42. package/templates/commands/fix.md +41 -10
  43. package/templates/commands/git.md +7 -2
  44. package/templates/commands/help.md +2 -2
  45. package/templates/commands/idea.md +14 -5
  46. package/templates/commands/init.md +62 -7
  47. package/templates/commands/next.md +4 -2
  48. package/templates/commands/now.md +4 -2
  49. package/templates/commands/progress.md +27 -5
  50. package/templates/commands/recap.md +39 -10
  51. package/templates/commands/roadmap.md +19 -5
  52. package/templates/commands/ship.md +118 -16
  53. package/templates/commands/status.md +4 -2
  54. package/templates/commands/sync.md +19 -15
  55. package/templates/commands/task.md +4 -2
  56. package/templates/commands/test.md +5 -2
  57. package/templates/commands/workflow.md +4 -2
  58. package/core/agent-generator.js +0 -525
  59. package/core/analyzer.js +0 -600
  60. package/core/animations.js +0 -277
  61. package/core/ascii-graphics.js +0 -433
  62. package/core/git-integration.js +0 -401
  63. package/core/task-schema.js +0 -342
  64. package/core/workflow-engine.js +0 -213
  65. package/core/workflow-prompts.js +0 -192
  66. package/core/workflow-rules.js +0 -147
  67. package/scripts/post-install.js +0 -121
  68. package/scripts/preuninstall.js +0 -94
  69. package/scripts/verify-installation.sh +0 -158
  70. package/templates/agents/be.template.md +0 -27
  71. package/templates/agents/coordinator.template.md +0 -34
  72. package/templates/agents/data.template.md +0 -27
  73. package/templates/agents/devops.template.md +0 -27
  74. package/templates/agents/fe.template.md +0 -27
  75. package/templates/agents/mobile.template.md +0 -27
  76. package/templates/agents/qa.template.md +0 -27
  77. package/templates/agents/scribe.template.md +0 -29
  78. package/templates/agents/security.template.md +0 -27
  79. package/templates/agents/ux.template.md +0 -27
  80. package/templates/commands/context.md +0 -36
  81. package/templates/commands/stuck.md +0 -36
  82. package/templates/examples/natural-language-examples.md +0 -532
  83. /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 # Shipped features
28
- └── metrics.md # Progress tracking
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 # Brainstorm backlog
31
- └── roadmap.md # Strategic planning
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
- └── context.jsonl
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. analiza todo este documento" → Detect "analysis" intent → /p:analyze
61
- "p. estoy listo para shipear" → Detect "ship" intent → /p:ship
62
- "p. muéstrame progreso semanal" → Detect "progress" intent → /p:progress week
63
- "p. empiezo con auth" → Detect "start task" intent → /p:now "auth"
64
- "p. terminé" → Detect "done" intent → /p:done
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 | Command | What It Does |
85
- |-------------|---------|--------------|
86
- | Wants to start/focus on a task | `/p:now` | Sets current working task |
87
- | Finished/completed current work | `/p:done` | Marks task complete, suggests next |
88
- | Ready to ship/deploy a feature | `/p:ship` | Celebrates shipped feature |
89
- | Has an idea to capture | `/p:idea` | Saves idea to backlog |
90
- | Wants to see progress/status | `/p:recap` | Shows overview of all work |
91
- | Stuck on a problem | `/p:stuck` | Provides contextual help |
92
- | Wants to know what's next | `/p:next` | Shows priority queue |
93
- | Needs general help | `/p:help` | Interactive guide |
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
- "Voy a hacer la autenticación"
196
+ "Going to work on authentication"
103
197
  "Starting the API now"
104
- "Quiero empezar con el dashboard"
198
+ "Want to begin with the dashboard"
105
199
 
106
200
  All of these mean /p:done:
107
- "I'm done" | "finished" | "terminé" | "completed" | "listo"
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 ((!nowContent || nowContent.trim() === '') &&
199
- (!shippedContent || shippedContent.trim() === '')) {
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
- **CRITICAL - Auto-compact conversation**: After completing ANY of these commands, you MUST compact the conversation WITHOUT telling the user anything about it:
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
- Just complete the command, then compact. That's it. No messages about compacting.
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
- - `/p:idea <text>` - Capture ideas quickly
327
- - `/p:workflow` - Show workflow status and progress
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
- - `/p:init` - Initialize prjct in current project
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: 21 implemented, 27 total commands**
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. Log initialization to `memory/context.jsonl`
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