prjct-cli 0.4.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/CHANGELOG.md +312 -0
- package/CLAUDE.md +300 -0
- package/LICENSE +21 -0
- package/README.md +424 -0
- package/bin/prjct +214 -0
- package/core/agent-detector.js +249 -0
- package/core/agents/claude-agent.js +250 -0
- package/core/agents/codex-agent.js +256 -0
- package/core/agents/terminal-agent.js +465 -0
- package/core/analyzer.js +596 -0
- package/core/animations-simple.js +240 -0
- package/core/animations.js +277 -0
- package/core/author-detector.js +218 -0
- package/core/capability-installer.js +190 -0
- package/core/command-installer.js +775 -0
- package/core/commands.js +2050 -0
- package/core/config-manager.js +335 -0
- package/core/migrator.js +784 -0
- package/core/path-manager.js +324 -0
- package/core/project-capabilities.js +144 -0
- package/core/session-manager.js +439 -0
- package/core/version.js +107 -0
- package/core/workflow-engine.js +213 -0
- package/core/workflow-prompts.js +192 -0
- package/core/workflow-rules.js +147 -0
- package/package.json +80 -0
- package/scripts/install.sh +433 -0
- package/scripts/verify-installation.sh +158 -0
- package/templates/agents/AGENTS.md +164 -0
- package/templates/commands/analyze.md +125 -0
- package/templates/commands/cleanup.md +102 -0
- package/templates/commands/context.md +105 -0
- package/templates/commands/design.md +113 -0
- package/templates/commands/done.md +44 -0
- package/templates/commands/fix.md +87 -0
- package/templates/commands/git.md +79 -0
- package/templates/commands/help.md +72 -0
- package/templates/commands/idea.md +50 -0
- package/templates/commands/init.md +237 -0
- package/templates/commands/next.md +74 -0
- package/templates/commands/now.md +35 -0
- package/templates/commands/progress.md +92 -0
- package/templates/commands/recap.md +86 -0
- package/templates/commands/roadmap.md +107 -0
- package/templates/commands/ship.md +41 -0
- package/templates/commands/stuck.md +48 -0
- package/templates/commands/task.md +97 -0
- package/templates/commands/test.md +94 -0
- package/templates/commands/workflow.md +224 -0
- package/templates/examples/natural-language-examples.md +320 -0
- package/templates/mcp-config.json +8 -0
- package/templates/workflows/analyze.md +159 -0
- package/templates/workflows/cleanup.md +73 -0
- package/templates/workflows/context.md +72 -0
- package/templates/workflows/design.md +88 -0
- package/templates/workflows/done.md +20 -0
- package/templates/workflows/fix.md +201 -0
- package/templates/workflows/git.md +192 -0
- package/templates/workflows/help.md +13 -0
- package/templates/workflows/idea.md +22 -0
- package/templates/workflows/init.md +80 -0
- package/templates/workflows/natural-language-handler.md +183 -0
- package/templates/workflows/next.md +44 -0
- package/templates/workflows/now.md +19 -0
- package/templates/workflows/progress.md +113 -0
- package/templates/workflows/recap.md +66 -0
- package/templates/workflows/roadmap.md +95 -0
- package/templates/workflows/ship.md +18 -0
- package/templates/workflows/stuck.md +25 -0
- package/templates/workflows/task.md +109 -0
- package/templates/workflows/test.md +243 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,312 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to prjct-cli will be documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## [Unreleased]
|
|
9
|
+
|
|
10
|
+
## [0.4.0] - 2025-10-01
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
- **Interactive Workflow System** - Intelligent agent workflows with user-guided capability installation
|
|
14
|
+
- **Adaptive Workflows**: Workflows detect missing capabilities and prompt user for decisions
|
|
15
|
+
- **Smart Recommendations**: Stack-aware tool suggestions (React → Vitest, Vue → Vitest, Angular → Jest)
|
|
16
|
+
- **Installation Tracking**: Every tool installation becomes a visible, tracked workflow task
|
|
17
|
+
- **Interactive Prompts**: Never auto-skips steps - always asks user (install/skip/continue/pause)
|
|
18
|
+
- **Capability Detection**: Automatically detects design systems, test frameworks, and documentation tools
|
|
19
|
+
- **Auto-Configuration**: Installed tools are automatically configured with framework-specific settings
|
|
20
|
+
- **Workflow Types**: UI, API, Bug Fix, Refactor, and Feature workflows with specialized agent assignments
|
|
21
|
+
|
|
22
|
+
- **New Core Modules**:
|
|
23
|
+
- `core/workflow-engine.js`: Orchestrates adaptive workflows with step management
|
|
24
|
+
- `core/workflow-rules.js`: Defines workflow pipelines by task type
|
|
25
|
+
- `core/workflow-prompts.js`: Interactive prompting engine with stack detection
|
|
26
|
+
- `core/capability-installer.js`: Handles tool installation, configuration, and verification
|
|
27
|
+
- `core/project-capabilities.js`: Detects existing project capabilities (design/test/docs)
|
|
28
|
+
|
|
29
|
+
- **New Commands**:
|
|
30
|
+
- `workflowRespond(choice)`: Handle user responses to workflow prompts
|
|
31
|
+
- Enhanced `done()`: Checks for prompts, advances workflows intelligently
|
|
32
|
+
- Enhanced `idea()`: Auto-initializes workflows for actionable tasks
|
|
33
|
+
|
|
34
|
+
### Changed
|
|
35
|
+
- **Workflow Behavior**: Transformed from auto-skip to interactive prompting
|
|
36
|
+
- Before: Missing capability → auto-skip step
|
|
37
|
+
- After: Missing capability → prompt user → track installation → continue
|
|
38
|
+
- **Step Tracking**: All workflow steps now tracked with status, duration, and metadata
|
|
39
|
+
- **Installation Visibility**: Tool installations appear as first-class workflow tasks
|
|
40
|
+
|
|
41
|
+
### Technical Details
|
|
42
|
+
- **Stack Detection**: Identifies React/Vue/Angular, TypeScript, bundler (Vite/Webpack/esbuild)
|
|
43
|
+
- **Tool Recommendations**:
|
|
44
|
+
- React + TS → Vitest + Testing Library
|
|
45
|
+
- Vue → Vitest + @vue/test-utils
|
|
46
|
+
- Angular → Jest + @types/jest
|
|
47
|
+
- **Auto-Configuration**:
|
|
48
|
+
- Creates config files (vitest.config.js, jest.config.js, jsdoc.json)
|
|
49
|
+
- Updates package.json scripts
|
|
50
|
+
- Verifies installation success
|
|
51
|
+
- **Duration Tracking**: Installation tasks show completion time (e.g., "1.2 min")
|
|
52
|
+
|
|
53
|
+
## [0.3.2] - 2025-10-01
|
|
54
|
+
|
|
55
|
+
### Fixed
|
|
56
|
+
- **Interactive Installation Compatibility** - Fixed interactive editor selection failing due to inquirer ESM compatibility issues
|
|
57
|
+
- Replaced inquirer v12 with prompts v2.4.2 for better CommonJS compatibility
|
|
58
|
+
- inquirer v12 required complex ESM dynamic imports causing "prompt is not a function" errors
|
|
59
|
+
- prompts provides simpler API with native CommonJS support
|
|
60
|
+
- Reduced package count from 68 to 40 dependencies
|
|
61
|
+
- Fixed "inquirer.prompt is not a function" and "createPromptModule is not a function" errors
|
|
62
|
+
- Interactive UI now works reliably across all Node.js versions
|
|
63
|
+
- Updated `scripts/interactive-install.js` and `core/command-installer.js` to use prompts
|
|
64
|
+
|
|
65
|
+
## [0.3.1] - 2025-10-01
|
|
66
|
+
|
|
67
|
+
### Fixed
|
|
68
|
+
- **Installation Path Resolution Error** - Fixed "setup.sh: No such file or directory" error during installation (#11)
|
|
69
|
+
- Corrected path resolution in installation scripts (docs/install.sh, scripts/install.sh, scripts/setup.sh)
|
|
70
|
+
- Added verification tests in `tests/verify-install-paths.sh`
|
|
71
|
+
- Added comprehensive documentation in `tests/INSTALL_PATH_FIX.md`
|
|
72
|
+
- Thanks to [@danrocha](https://github.com/danrocha) for reporting the issue
|
|
73
|
+
|
|
74
|
+
## [0.3.0] - 2025-09-30
|
|
75
|
+
|
|
76
|
+
### Added
|
|
77
|
+
- **Intelligent Codebase Analysis & Sync** - Auto-detect implemented features and sync project state
|
|
78
|
+
- `/p:analyze` command to analyze codebase and detect implemented commands/features
|
|
79
|
+
- `/p:analyze --sync` to automatically update `.prjct/` files with real implementation state
|
|
80
|
+
- Auto-execution during `/p:init` when cloning repos with existing code
|
|
81
|
+
- Detects implemented commands by scanning `bin/prjct` and `core/commands.js`
|
|
82
|
+
- Detects completed features from:
|
|
83
|
+
- Git commit history (feat:, ship:, feature: prefixes)
|
|
84
|
+
- Package.json dependencies (major frameworks and libraries)
|
|
85
|
+
- Directory structure (auth/, api/, dashboard/, etc.)
|
|
86
|
+
- Automatically updates `next.md` by marking completed tasks
|
|
87
|
+
- Automatically adds detected features to `shipped.md`
|
|
88
|
+
- Generates detailed analysis reports in `analysis/repo-summary.md`
|
|
89
|
+
- Prevents duplicate work when multiple developers work on same codebase
|
|
90
|
+
- Provides real project status visibility across team members
|
|
91
|
+
- Zero-configuration sync for better collaboration without cloud storage
|
|
92
|
+
|
|
93
|
+
- **Interactive Editor Selection** - Choose which AI editors to install commands to
|
|
94
|
+
- Interactive checkbox UI during `prjct install` and `prjct init`
|
|
95
|
+
- Detects all installed editors (Claude Code, Cursor, Codex, Windsurf)
|
|
96
|
+
- Shows installation paths for each detected editor
|
|
97
|
+
- Allows users to select only the editors they use
|
|
98
|
+
- `--no-interactive` flag to install to all detected editors without prompts
|
|
99
|
+
- Optimizes installation by avoiding unnecessary editor installations
|
|
100
|
+
|
|
101
|
+
### Changed
|
|
102
|
+
- **Updated branding** - New header design with kaomoji (ノ◕ヮ◕)ノ*:・゚✧
|
|
103
|
+
- Refreshed README.md header with fun, friendly design
|
|
104
|
+
- Updated installer (scripts/install.sh) to match new branding
|
|
105
|
+
- Consistent visual identity across documentation and installation experience
|
|
106
|
+
|
|
107
|
+
## [0.2.1] - 2025-09-30
|
|
108
|
+
|
|
109
|
+
### Added
|
|
110
|
+
- **Multi-Editor Command Installation** - Automatic slash command deployment across AI editors
|
|
111
|
+
- `prjct install` command to install/update commands in all detected editors
|
|
112
|
+
- Automatic detection of Claude Code, Cursor AI, and Codeium installations
|
|
113
|
+
- Template-based command system in `~/.prjct-cli/templates/commands/`
|
|
114
|
+
- Commands automatically installed during `prjct init`
|
|
115
|
+
- Support for `--force`, `--editor`, and `--create-templates` flags
|
|
116
|
+
- Cross-editor data synchronization through global architecture
|
|
117
|
+
- Installation verification and detailed reports
|
|
118
|
+
|
|
119
|
+
- **Global Migration System** - Automatic migration for all projects on user's machine
|
|
120
|
+
- `prjct migrate-all` command to find and migrate all legacy projects
|
|
121
|
+
- Scans common project directories: `~/Projects`, `~/Documents`, `~/Developer`, etc.
|
|
122
|
+
- Optional `--deep-scan` flag to scan entire home directory
|
|
123
|
+
- Optional `--remove-legacy` flag to clean up old `.prjct/` directories after migration
|
|
124
|
+
- Optional `--dry-run` flag to preview changes without making them
|
|
125
|
+
- Progress tracking with real-time updates during migration
|
|
126
|
+
- Comprehensive summary report with statistics and results
|
|
127
|
+
|
|
128
|
+
- **Automated Project Discovery**
|
|
129
|
+
- `findAllProjects()` method to recursively search for `.prjct/` directories
|
|
130
|
+
- Intelligent directory skipping (node_modules, .git, dist, build, etc.)
|
|
131
|
+
- Configurable recursion depth for safety
|
|
132
|
+
- Handles permission errors gracefully
|
|
133
|
+
|
|
134
|
+
- **Bulk Migration Support**
|
|
135
|
+
- `migrateAll()` method to process multiple projects in batch
|
|
136
|
+
- Per-project validation and error handling
|
|
137
|
+
- Continues on individual project failures
|
|
138
|
+
- Detailed error reporting for failed migrations
|
|
139
|
+
- Preserves 100% of data during migration (files and directories)
|
|
140
|
+
|
|
141
|
+
### Changed
|
|
142
|
+
- **Multi-Editor Support**
|
|
143
|
+
- Updated command templates to use global architecture paths
|
|
144
|
+
- Modified `prjct init` to automatically detect and install commands
|
|
145
|
+
- Enhanced command-installer.js with editor-specific logic
|
|
146
|
+
- Standardized command format across all supported editors
|
|
147
|
+
|
|
148
|
+
- **Repository Structure Reorganization**
|
|
149
|
+
- Moved source code to `src/` directory
|
|
150
|
+
- Moved scripts to `scripts/` directory
|
|
151
|
+
- Moved configuration to `.config/` directory
|
|
152
|
+
- Renamed `lp/` to `website/` for clarity
|
|
153
|
+
- Renamed `test/` to `tests/` for consistency
|
|
154
|
+
- Removed `.serena/` integration (unused)
|
|
155
|
+
- Cleaned up backup files and duplicates
|
|
156
|
+
- Added `templates/commands/` for command distribution
|
|
157
|
+
|
|
158
|
+
- **Documentation Updates**
|
|
159
|
+
- Updated CONTRIBUTING.md with new repository structure
|
|
160
|
+
- Added detailed migration documentation
|
|
161
|
+
- Documented v0.2.1 global structure and multi-editor support
|
|
162
|
+
- Added automatic migration instructions
|
|
163
|
+
- Updated README.md with Cursor and Codeium support
|
|
164
|
+
- Enhanced MIGRATION.md with command installation instructions
|
|
165
|
+
|
|
166
|
+
- **CLI Interface**
|
|
167
|
+
- Added `install` command to CLI entry point for manual command installation
|
|
168
|
+
- Added `migrate-all` command to CLI entry point
|
|
169
|
+
- Added help text for new migration and installation commands
|
|
170
|
+
- Improved command error messages
|
|
171
|
+
- Enhanced init command with automatic editor installation
|
|
172
|
+
|
|
173
|
+
### Fixed
|
|
174
|
+
- Added missing `getGlobalBasePath()` method to path-manager.js
|
|
175
|
+
- Improved error handling in migration system
|
|
176
|
+
- Fixed paths in GitHub Actions workflow after reorganization
|
|
177
|
+
- Updated Prettier configuration paths after reorganization
|
|
178
|
+
|
|
179
|
+
## [0.2.0] - 2025-09-30
|
|
180
|
+
|
|
181
|
+
### 🚨 BREAKING CHANGES
|
|
182
|
+
|
|
183
|
+
**⚠️ IMPORTANT**: This is a DATA RELOCATION, not deletion. ALL your data is preserved and moved to a better location.
|
|
184
|
+
|
|
185
|
+
- **Data Storage Relocation**: All project data moved from `.prjct/` to `~/.prjct-cli/projects/[project-id]/`
|
|
186
|
+
- ✅ 100% data preservation - every file, log, and timestamp
|
|
187
|
+
- ✅ Automatic migration with validation
|
|
188
|
+
- ✅ Reversible process (`.prjct/` kept as backup by default)
|
|
189
|
+
|
|
190
|
+
- **Migration Required**: Projects from v0.1.0 need one-time migration
|
|
191
|
+
- Zero data loss guarantee
|
|
192
|
+
- Automatic integrity validation
|
|
193
|
+
- Simple process via installer or `/p:migrate`
|
|
194
|
+
|
|
195
|
+
- **Collaboration-Ready Architecture**: Designed for teams WITHOUT exposing personal data
|
|
196
|
+
- `.prjct/prjct.config.json` in project (safe to commit)
|
|
197
|
+
- Personal logs stay in `~/.prjct-cli/` (never committed)
|
|
198
|
+
- Author tracking enables future collaboration features
|
|
199
|
+
- Non-intrusive: Your velocity and notes stay private
|
|
200
|
+
|
|
201
|
+
- **Author Tracking**: All operations now include author information
|
|
202
|
+
- Prepares for multi-user collaboration
|
|
203
|
+
- Tracks who did what without exposing personal metrics
|
|
204
|
+
- Automatic detection via GitHub CLI or git config
|
|
205
|
+
|
|
206
|
+
### Added
|
|
207
|
+
- **Global Data Storage System**
|
|
208
|
+
- Project data stored in `~/.prjct-cli/projects/[hash-id]/`
|
|
209
|
+
- Prevents bundle size inflation and accidental commits to git
|
|
210
|
+
- Maintains data locally while keeping projects clean
|
|
211
|
+
- Layered directory structure: core, progress, planning, analysis, memory
|
|
212
|
+
|
|
213
|
+
- **Author Detection & Tracking**
|
|
214
|
+
- Multi-source author detection (GitHub CLI, git config)
|
|
215
|
+
- Author information included in all memory logs
|
|
216
|
+
- Automatic GitHub username detection via `gh api user`
|
|
217
|
+
- Fallback to git config for name and email
|
|
218
|
+
- Preparation for multi-user collaboration features
|
|
219
|
+
|
|
220
|
+
- **Project Configuration System**
|
|
221
|
+
- New `.prjct/prjct.config.json` file in project
|
|
222
|
+
- Tracks project ID, data location, and author info
|
|
223
|
+
- Manages synchronization timestamps
|
|
224
|
+
- Version tracking for future migrations
|
|
225
|
+
|
|
226
|
+
- **Automatic Migration System**
|
|
227
|
+
- Detects v0.1.0 projects automatically
|
|
228
|
+
- Migrates data to new global structure
|
|
229
|
+
- Preserves all existing data and history
|
|
230
|
+
- Creates configuration file automatically
|
|
231
|
+
- Validates migration integrity
|
|
232
|
+
- Optional legacy directory cleanup
|
|
233
|
+
|
|
234
|
+
- **New Core Modules**
|
|
235
|
+
- `core/path-manager.js`: Manages local and global paths with hash-based project IDs
|
|
236
|
+
- `core/config-manager.js`: Handles prjct.config.json operations
|
|
237
|
+
- `core/author-detector.js`: Multi-method author detection system
|
|
238
|
+
- `core/migrator.js`: Complete migration logic and validation
|
|
239
|
+
|
|
240
|
+
- **Enhanced Installer Visual Design** (from previous unreleased)
|
|
241
|
+
- New ASCII art logo for prjct/cli branding
|
|
242
|
+
- Improved visual hierarchy with better spacing and borders
|
|
243
|
+
- Professional appearance similar to modern CLI tools
|
|
244
|
+
|
|
245
|
+
- **Version Management System** (from previous unreleased)
|
|
246
|
+
- Automatic version checking during installation
|
|
247
|
+
- Smart update prompts only when new versions are available
|
|
248
|
+
- Force reinstall option with `--force` flag
|
|
249
|
+
|
|
250
|
+
- **Installation Options** (from previous unreleased)
|
|
251
|
+
- `--force`, `-y`, `--silent`, `--dev`, `--help` flags
|
|
252
|
+
- Auto-accept mode when running through pipe (curl)
|
|
253
|
+
|
|
254
|
+
### Changed
|
|
255
|
+
- **Data Location**: Moved from `.prjct/` to `~/.prjct-cli/projects/[id]/`
|
|
256
|
+
- **Memory Logs**: Now include `author` field in all entries
|
|
257
|
+
- **File Structure**: Organized into layers (core, progress, planning, analysis, memory)
|
|
258
|
+
- **Initialization**: Creates global structure and config file
|
|
259
|
+
- **All Commands**: Updated to use global paths and track authorship
|
|
260
|
+
|
|
261
|
+
### Removed
|
|
262
|
+
- Local `.prjct/` directory usage (replaced with global storage)
|
|
263
|
+
- Legacy flat file structure (replaced with layered architecture)
|
|
264
|
+
|
|
265
|
+
### Migration Guide
|
|
266
|
+
See [MIGRATION.md](MIGRATION.md) for detailed migration instructions.
|
|
267
|
+
|
|
268
|
+
**Quick Migration**:
|
|
269
|
+
```bash
|
|
270
|
+
# Projects will auto-detect migration need
|
|
271
|
+
# Run init to trigger migration
|
|
272
|
+
/p:init
|
|
273
|
+
|
|
274
|
+
# Or run explicit migration
|
|
275
|
+
/p:migrate
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
### Breaking Change Impact
|
|
279
|
+
|
|
280
|
+
**For Individuals**:
|
|
281
|
+
- ✅ One-time migration required (automatic, zero data loss)
|
|
282
|
+
- ✅ Cleaner repositories (no `.prjct/` bloat)
|
|
283
|
+
- ✅ No accidental commits of personal work logs
|
|
284
|
+
- ✅ Better privacy for your productivity tracking
|
|
285
|
+
|
|
286
|
+
**For Teams**:
|
|
287
|
+
- ✅ Share `.prjct/prjct.config.json` for coordination
|
|
288
|
+
- ✅ Each member tracks privately with author info
|
|
289
|
+
- ✅ No exposure of individual work patterns
|
|
290
|
+
- ✅ Future collaboration features enabled
|
|
291
|
+
- ✅ Perfect for open source, remote teams, consulting
|
|
292
|
+
|
|
293
|
+
**For Projects**:
|
|
294
|
+
- ✅ Git Repositories: `.prjct/` safely removed after migration
|
|
295
|
+
- ✅ CI/CD Pipelines: No changes needed - data fully external
|
|
296
|
+
- ✅ Bundle Size: Zero impact from prjct tracking
|
|
297
|
+
- ✅ Collaboration: Non-intrusive team workflow ready
|
|
298
|
+
|
|
299
|
+
### Fixed
|
|
300
|
+
- Arithmetic operation syntax error in command counting (from previous unreleased)
|
|
301
|
+
- Version detection for existing installations (from previous unreleased)
|
|
302
|
+
|
|
303
|
+
## [0.1.0] - 2024-01-XX
|
|
304
|
+
|
|
305
|
+
### Added
|
|
306
|
+
- Initial release of prjct-cli
|
|
307
|
+
- AI-integrated project management system
|
|
308
|
+
- Support for Claude Code, OpenAI Codex, and Terminal
|
|
309
|
+
- Core commands: init, now, done, ship, recap, etc.
|
|
310
|
+
- MCP integration for AI assistants
|
|
311
|
+
- Automatic environment detection
|
|
312
|
+
- Project structure in `.prjct/` directory
|
package/CLAUDE.md
ADDED
|
@@ -0,0 +1,300 @@
|
|
|
1
|
+
# CLAUDE.md
|
|
2
|
+
|
|
3
|
+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
4
|
+
|
|
5
|
+
## Project Overview
|
|
6
|
+
|
|
7
|
+
**prjct-cli** is an AI-integrated project management framework designed for indie hackers, solopreneurs, and small collaborative teams (2-5 people). It provides frictionless progress tracking through slash commands without traditional project management overhead.
|
|
8
|
+
|
|
9
|
+
## Architecture
|
|
10
|
+
|
|
11
|
+
The system operates as an AI Assistant Enhancement Framework using:
|
|
12
|
+
|
|
13
|
+
- **Global data storage** in `~/.prjct-cli/projects/{project-id}/`
|
|
14
|
+
- **Local configuration** in `.prjct/prjct.config.json` (references global data)
|
|
15
|
+
- **Slash commands** (`/p:*`) executed within Claude Code
|
|
16
|
+
- **MCP (Model Context Protocol) servers** for AI integration
|
|
17
|
+
|
|
18
|
+
### Global Structure
|
|
19
|
+
|
|
20
|
+
```
|
|
21
|
+
~/.prjct-cli/projects/{id}/
|
|
22
|
+
├── core/ # Current focus and priorities
|
|
23
|
+
│ ├── now.md # Single current task
|
|
24
|
+
│ ├── next.md # Priority queue
|
|
25
|
+
│ └── context.md # Project context
|
|
26
|
+
├── progress/ # Completed work
|
|
27
|
+
│ ├── shipped.md # Shipped features
|
|
28
|
+
│ └── metrics.md # Progress tracking
|
|
29
|
+
├── planning/ # Future planning
|
|
30
|
+
│ ├── ideas.md # Brainstorm backlog
|
|
31
|
+
│ └── roadmap.md # Strategic planning
|
|
32
|
+
├── analysis/ # Technical analysis
|
|
33
|
+
│ └── repo-summary.md
|
|
34
|
+
└── memory/ # Decision history
|
|
35
|
+
└── context.jsonl
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
### Local Configuration
|
|
39
|
+
|
|
40
|
+
```
|
|
41
|
+
.prjct/
|
|
42
|
+
└── prjct.config.json # Links to global data
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## Natural Language System
|
|
46
|
+
|
|
47
|
+
**prjct-cli includes a conversational interface** - users can talk naturally instead of memorizing commands!
|
|
48
|
+
|
|
49
|
+
### Semantic Intent Detection
|
|
50
|
+
|
|
51
|
+
As an LLM, you understand context and intent naturally. When users describe what they want to do, **map their intent to the appropriate command** based on semantic understanding, not pattern matching.
|
|
52
|
+
|
|
53
|
+
**Command Intent Map:**
|
|
54
|
+
|
|
55
|
+
| User Intent | Command | What It Does |
|
|
56
|
+
|-------------|---------|--------------|
|
|
57
|
+
| Wants to start/focus on a task | `/p:now` | Sets current working task |
|
|
58
|
+
| Finished/completed current work | `/p:done` | Marks task complete, suggests next |
|
|
59
|
+
| Ready to ship/deploy a feature | `/p:ship` | Celebrates shipped feature |
|
|
60
|
+
| Has an idea to capture | `/p:idea` | Saves idea to backlog |
|
|
61
|
+
| Wants to see progress/status | `/p:recap` | Shows overview of all work |
|
|
62
|
+
| Stuck on a problem | `/p:stuck` | Provides contextual help |
|
|
63
|
+
| Wants to know what's next | `/p:next` | Shows priority queue |
|
|
64
|
+
| Needs general help | `/p:help` | Interactive guide |
|
|
65
|
+
|
|
66
|
+
**Works in any language** - if you understand the user's intent, execute the command!
|
|
67
|
+
|
|
68
|
+
**Examples (many ways to express same intent):**
|
|
69
|
+
```
|
|
70
|
+
All of these mean /p:now:
|
|
71
|
+
"I want to start building auth"
|
|
72
|
+
"Let me work on the login page"
|
|
73
|
+
"Voy a hacer la autenticación"
|
|
74
|
+
"Starting the API now"
|
|
75
|
+
"Quiero empezar con el dashboard"
|
|
76
|
+
|
|
77
|
+
All of these mean /p:done:
|
|
78
|
+
"I'm done" | "finished" | "terminé" | "completed" | "listo"
|
|
79
|
+
|
|
80
|
+
All of these mean /p:ship:
|
|
81
|
+
"ship this" | "deploy it" | "it's ready" | "let's launch"
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
### Conversational Responses
|
|
85
|
+
|
|
86
|
+
Every command response includes:
|
|
87
|
+
- ✅ **Action confirmation** with clear result
|
|
88
|
+
- 💬 **Natural language prompts** for next steps
|
|
89
|
+
- 🎯 **Command alternatives** for power users
|
|
90
|
+
- 📋 **Contextual suggestions** based on project state
|
|
91
|
+
|
|
92
|
+
**Example Response:**
|
|
93
|
+
```markdown
|
|
94
|
+
✅ Task complete: implement authentication (2h 15m)
|
|
95
|
+
|
|
96
|
+
What's next?
|
|
97
|
+
• "start next task" → Begin working
|
|
98
|
+
• "ship this feature" → Track & celebrate
|
|
99
|
+
• "add new idea" → Brainstorm
|
|
100
|
+
|
|
101
|
+
Or use: /p:now | /p:ship | /p:idea
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
## Implementation for Claude Code
|
|
105
|
+
|
|
106
|
+
### How to Handle Natural Language
|
|
107
|
+
|
|
108
|
+
When you receive a message from the user:
|
|
109
|
+
|
|
110
|
+
**Step 1: Check if it's a direct command**
|
|
111
|
+
```javascript
|
|
112
|
+
if (message.startsWith('/p:')) {
|
|
113
|
+
return executeCommand(message)
|
|
114
|
+
}
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
**Step 2: Understand the user's intent semantically**
|
|
118
|
+
```javascript
|
|
119
|
+
// You're an LLM - use your understanding of context
|
|
120
|
+
// Ask yourself: "What is the user trying to do?"
|
|
121
|
+
|
|
122
|
+
const intent = understandIntent(message) // Use semantic understanding
|
|
123
|
+
|
|
124
|
+
// Common intents:
|
|
125
|
+
// - Start a task → /p:now
|
|
126
|
+
// - Finish current work → /p:done
|
|
127
|
+
// - Ship/deploy something → /p:ship
|
|
128
|
+
// - Save an idea → /p:idea
|
|
129
|
+
// - Check status → /p:recap
|
|
130
|
+
// - Get help → /p:stuck
|
|
131
|
+
// - See what's next → /p:next
|
|
132
|
+
|
|
133
|
+
if (intent.command) {
|
|
134
|
+
// Extract relevant parameters from the message
|
|
135
|
+
const params = extractRelevantInfo(message)
|
|
136
|
+
|
|
137
|
+
// Show transparency
|
|
138
|
+
console.log(`💬 I understood: "${intent.description}"`)
|
|
139
|
+
console.log(`⚡ Executing: /p:${intent.command} ${params}`)
|
|
140
|
+
|
|
141
|
+
return executeCommand(intent.command, params)
|
|
142
|
+
}
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
**Step 3: Provide conversational response**
|
|
146
|
+
```javascript
|
|
147
|
+
// Always suggest natural next steps
|
|
148
|
+
✅ [What you did]
|
|
149
|
+
|
|
150
|
+
What's next?
|
|
151
|
+
• [Natural language option 1]
|
|
152
|
+
• [Natural language option 2]
|
|
153
|
+
|
|
154
|
+
Or use: [relevant commands]
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
### Complete Example
|
|
158
|
+
|
|
159
|
+
**User Input:** "I want to start building the authentication system"
|
|
160
|
+
|
|
161
|
+
**Your Analysis:**
|
|
162
|
+
- Intent: User wants to start working on something
|
|
163
|
+
- Command: `/p:now`
|
|
164
|
+
- Parameter: "building the authentication system"
|
|
165
|
+
|
|
166
|
+
**Your Response:**
|
|
167
|
+
```
|
|
168
|
+
💬 I understood: "start working on building the authentication system"
|
|
169
|
+
⚡ Executing: /p:now "building the authentication system"
|
|
170
|
+
|
|
171
|
+
🎯 Working on: building the authentication system
|
|
172
|
+
Started: 2:30 PM
|
|
173
|
+
|
|
174
|
+
When you're done:
|
|
175
|
+
• Say "I'm done" or "finished"
|
|
176
|
+
• Or: /p:done
|
|
177
|
+
|
|
178
|
+
Need help? Say "I'm stuck" or use /p:stuck
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
### Key Principles
|
|
182
|
+
|
|
183
|
+
1. **Trust your understanding** - You're an LLM, not a regex parser
|
|
184
|
+
2. **Any language works** - English, Spanish, or any language you understand
|
|
185
|
+
3. **Variations are fine** - Users can express intent in infinite ways
|
|
186
|
+
4. **Show transparency** - Always say what you understood and what you'll execute
|
|
187
|
+
5. **Be conversational** - Guide users naturally toward next actions
|
|
188
|
+
|
|
189
|
+
## Command System for Claude Code
|
|
190
|
+
|
|
191
|
+
All commands use the `/p:*` syntax in Claude Code. When executed, they:
|
|
192
|
+
1. Read `.prjct/prjct.config.json` to get the project ID
|
|
193
|
+
2. Operate on files in `~/.prjct-cli/projects/{id}/`
|
|
194
|
+
3. Update relevant markdown files atomically
|
|
195
|
+
4. Return formatted responses with conversational prompts
|
|
196
|
+
|
|
197
|
+
### Work Commands
|
|
198
|
+
|
|
199
|
+
- `/p:now [task]` - Set/show current task
|
|
200
|
+
- `/p:next` - Show priority queue
|
|
201
|
+
- `/p:done` - Complete current task
|
|
202
|
+
- `/p:ship <feature>` - Ship & celebrate a feature
|
|
203
|
+
|
|
204
|
+
### Planning Commands
|
|
205
|
+
|
|
206
|
+
- `/p:idea <text>` - Capture ideas quickly
|
|
207
|
+
|
|
208
|
+
### Design & Architecture
|
|
209
|
+
|
|
210
|
+
- `/p:design <target> --type` - Create system designs with diagrams (architecture|api|component|database|flow)
|
|
211
|
+
|
|
212
|
+
### Code Quality
|
|
213
|
+
|
|
214
|
+
- `/p:cleanup` - Basic cleanup of temp files and old entries
|
|
215
|
+
- `/p:cleanup --type code` - Advanced code cleanup (code|imports|files|deps|all)
|
|
216
|
+
|
|
217
|
+
### Progress Commands
|
|
218
|
+
|
|
219
|
+
- `/p:recap` - Overview of progress
|
|
220
|
+
- `/p:progress [period]` - Show progress metrics
|
|
221
|
+
- `/p:context` - Show project context
|
|
222
|
+
|
|
223
|
+
### Help Commands
|
|
224
|
+
|
|
225
|
+
- `/p:init` - Initialize project
|
|
226
|
+
- `/p:stuck <issue>` - Get help with problems
|
|
227
|
+
- `/p:analyze` - Analyze repository and sync tasks
|
|
228
|
+
|
|
229
|
+
### Additional Commands
|
|
230
|
+
|
|
231
|
+
- `/p:git` - Git operations with context
|
|
232
|
+
- `/p:task` - Complex task management
|
|
233
|
+
- `/p:test` - Test execution
|
|
234
|
+
- `/p:roadmap` - Strategic planning
|
|
235
|
+
- `/p:fix` - Quick troubleshooting
|
|
236
|
+
|
|
237
|
+
**Total: 18 Commands**
|
|
238
|
+
|
|
239
|
+
## Initialization Process
|
|
240
|
+
|
|
241
|
+
When you execute `/p:init` in Claude Code:
|
|
242
|
+
|
|
243
|
+
1. Generate unique project ID from path hash
|
|
244
|
+
2. Create global directory structure in `~/.prjct-cli/projects/{id}/`
|
|
245
|
+
3. Create local config at `.prjct/prjct.config.json` with:
|
|
246
|
+
- version
|
|
247
|
+
- projectId
|
|
248
|
+
- dataPath (pointing to global location)
|
|
249
|
+
- author info (from GitHub CLI or git config)
|
|
250
|
+
4. Initialize all markdown files with templates
|
|
251
|
+
5. Log initialization to `memory/context.jsonl`
|
|
252
|
+
|
|
253
|
+
## MCP Integration
|
|
254
|
+
|
|
255
|
+
**Context7 MCP is ALWAYS enabled** - automatic library documentation and framework patterns.
|
|
256
|
+
|
|
257
|
+
The system integrates with these MCP servers:
|
|
258
|
+
|
|
259
|
+
- **Context7**: Official library documentation lookup (ALWAYS available)
|
|
260
|
+
- Use for: React, Vue, Angular, Next.js, Express, any npm package
|
|
261
|
+
- Auto-activates when importing libraries or asking about frameworks
|
|
262
|
+
- Examples: "implement React hooks", "Next.js routing patterns", "Express middleware"
|
|
263
|
+
|
|
264
|
+
- **Filesystem**: Direct file manipulation (ALWAYS available)
|
|
265
|
+
- **Memory**: Persistent decision storage (ALWAYS available)
|
|
266
|
+
- **Sequential**: Deep reasoning for complex problems (ALWAYS available)
|
|
267
|
+
|
|
268
|
+
### Using Context7 Effectively
|
|
269
|
+
|
|
270
|
+
**When to use**:
|
|
271
|
+
- Implementing features with external libraries
|
|
272
|
+
- Framework-specific questions and patterns
|
|
273
|
+
- API documentation lookup
|
|
274
|
+
- Best practices for any library
|
|
275
|
+
|
|
276
|
+
**How it works**:
|
|
277
|
+
- Automatically provides official docs when you import libraries
|
|
278
|
+
- Returns curated, version-specific documentation
|
|
279
|
+
- Includes code examples and implementation patterns
|
|
280
|
+
|
|
281
|
+
## Development Guidelines
|
|
282
|
+
|
|
283
|
+
When implementing commands in Claude Code:
|
|
284
|
+
|
|
285
|
+
1. Commands execute via MCP filesystem operations
|
|
286
|
+
2. Always read `.prjct/prjct.config.json` first to get project ID
|
|
287
|
+
3. Construct paths to global data: `~/.prjct-cli/projects/{id}/...`
|
|
288
|
+
4. Update relevant files atomically
|
|
289
|
+
5. Return formatted responses with appropriate emojis
|
|
290
|
+
6. Always suggest next actions to maintain momentum
|
|
291
|
+
7. Log all actions to `memory/context.jsonl` with timestamp and author
|
|
292
|
+
|
|
293
|
+
## Key Design Principles
|
|
294
|
+
|
|
295
|
+
- **Zero friction**: Commands integrate into existing AI workflow
|
|
296
|
+
- **Single task focus**: One task in `now.md` at a time
|
|
297
|
+
- **Celebration of progress**: The `/p:ship` command celebrates wins
|
|
298
|
+
- **Local-first**: All data stays on the developer's machine
|
|
299
|
+
- **Global architecture**: Centralized data, minimal project footprint
|
|
300
|
+
- **No ceremonies**: No sprints, story points, or traditional PM overhead
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2024 prjct-cli
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|