npm - context-first-cli - Versions diffs - 1.8.0 → 1.8.2 - Mend

context-first-cli 1.8.0 → 1.8.2

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 (4) hide show

package/README.md +524 -149
package/dist/templates/commands/engineer/work.md +24 -20
package/package.json +1 -1
package/templates/commands/engineer/work.md +24 -20

package/README.md CHANGED Viewed

@@ -1,276 +1,651 @@
 # Context-First CLI
-A generic, cross-platform CLI to manage the **Context-First** development methodology across any project ecosystem. This tool provides a robust framework for orchestrating development workflows, managing multiple repositories, and ensuring consistency for both human developers and AI agents.
+> A universal CLI for managing Context-First development methodology across any project ecosystem.
+Orchestrate multi-repository workflows, create isolated feature workspaces, and maintain consistency for both human developers and AI agents.
+[![npm version](https://img.shields.io/npm/v/context-first-cli.svg)](https://www.npmjs.com/package/context-first-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+---
+## Table of Contents
+- [Why Context-First CLI?](#why-context-first-cli)
+- [Quick Start](#quick-start)
+- [Core Concepts](#core-concepts)
+- [Installation](#installation)
+- [Commands](#commands)
+- [Workflow Guide](#workflow-guide)
+- [Docker Support](#docker-support)
+- [Architecture](#architecture)
+- [Examples](#examples)
+- [Troubleshooting](#troubleshooting)
+---
+## Why Context-First CLI?
+**The Problem**: Managing multiple repositories, coordinating feature development, and maintaining consistent processes across teams is complex and error-prone.
+**The Solution**: Context-First CLI provides:
+✅ **Isolated Feature Workspaces** - Work on multiple features simultaneously without conflicts
+✅ **Git Worktree Integration** - Efficient branch management without re-cloning repositories
+✅ **Docker Support** - Automatic `docker-compose.yml` generation with dynamic ports
+✅ **AI-Ready** - Pre-configured command templates for AI assistants (Claude, Cursor)
+✅ **Cross-Platform** - Works on Windows, macOS, and Linux
+✅ **Project-Agnostic** - One CLI for all your projects
+---
+## Quick Start
+```bash
+# 1. Install globally
+npm install -g context-first-cli
+# 2. Create orchestrator (project control center)
+npx context-first-cli@latest create:orchestrator
+# 3. Configure local environment
+cd your-orchestrator/
+npx context-first-cli@latest config:setup
+# 4. Add repositories
+npx context-first-cli@latest add:repo
+# 5. Start working on a feature
+npx context-first-cli@latest feature start FIN-123
+# 6. Enter workspace and start services
+cd .sessions/FIN-123
+docker-compose up -d
+```
+**That's it!** You now have an isolated workspace with all repositories checked out and services running.
 ---
-## 🚀 Core Concepts
+## Core Concepts
-This CLI is built on three core concepts that enable scalable, parallel, and context-aware development.
+### 1. Orchestrator Repository
-### 1. The Orchestrator Repository
+The **single source of truth** for your project's development process.
-Instead of embedding process logic into each of your application repositories, you define it in one central **Orchestrator Repository**. This repository acts as the single source of truth for your development methodology. It contains:
+**Contains**:
+- `context-manifest.json` - Repository definitions and relationships
+- `.claude/commands/` - AI command templates
+- `ai.properties.md` - Local configuration (gitignored)
+- `.contextrc.json` - Makes orchestrator self-aware
--   **Command Definitions**: Markdown files (`.claude/commands/`) that instruct an AI (like Claude) on the purpose and logic of each step in your process (e.g., `/work`, `/spec`, `/pr`).
--   **Repository Manifest**: A `context-manifest.json` file that maps out your entire project ecosystem, defining all repositories (including MetaSpecs) and their relationships.
--   **Configuration Templates**: Files like `ai.properties.md` that define project-specific commands (lint, test, build) and settings.
+**Purpose**: Define your development methodology once, use everywhere.
 ### 2. Feature Workspaces
-To enable parallel development without conflicts, the CLI uses **Feature Workspaces**. When you start working on a new feature (e.g., an issue from Jira), the CLI creates a dedicated, isolated directory. Inside this workspace, it uses `git worktree` to check out a specific branch for each relevant repository. This is extremely efficient, as it doesn't re-clone the entire repository, saving disk space and time.
+**Isolated environments** for each feature you work on.
+**Location**: `orchestrator/.sessions/<ISSUE-ID>/`
+**Contains**:
+- Git worktrees for each repository (efficient, no re-cloning)
+- `docker-compose.yml` with dynamic ports
+- Feature-specific documentation
--   **Isolation**: Every feature has its own folder, preventing any overlap or context-clash between concurrent tasks.
--   **Efficiency**: Powered by `git worktree`, creating and switching between workspaces is nearly instantaneous.
--   **Docker Support**: Automatically generates `docker-compose.yml` with dynamic ports based on issue number, allowing multiple workspaces to run simultaneously without port conflicts.
+**Benefits**:
+- Work on multiple features simultaneously
+- No port conflicts (FIN-11 → 3011, FIN-12 → 3012)
+- Clean separation of concerns
-### 3. The Agnostic CLI (`context-cli`)
+### 3. Git Worktree
-This is the tool you install on your machine. It's completely project-agnostic. You can use the same CLI to manage any project.
+**Efficient branch management** without multiple clones.
+**How it works**:
+```
+Main Repository (~/dev/backend):
+└── main branch
--   **Cross-Platform**: Built with Node.js/TypeScript, it works seamlessly on Windows, macOS, and Linux.
--   **Configurable**: The `init` command creates a `.contextrc.json` file in your project, telling the CLI which Orchestrator to use.
--   **AI-Agnostic**: You can configure it to create command structures for different AI providers (e.g., `.claude/commands` for Claude, `.cursor/commands` for Cursor).
+Workspace 1 (.sessions/FIN-11/backend):
+└── feature/FIN-11 branch (worktree)
+Workspace 2 (.sessions/FIN-12/backend):
+└── feature/FIN-12 branch (worktree)
+```
+**All share the same `.git/`** - saving disk space and time.
 ---
-## 📦 Installation
+## Installation
-Install the CLI globally on your machine via NPM.
+### Global Installation (Recommended)
 ```bash
 npm install -g context-first-cli
 ```
+### Use Without Installing
+```bash
+npx context-first-cli@latest <command>
+```
+### Requirements
+- Node.js >= 18.0.0
+- Git >= 2.5.0
+- Docker (optional, for container support)
 ---
-## 📋 Commands Reference
+## Commands
 ### Setup Commands
 | Command | Description |
-| :--- | :--- |
-| `context-cli init` | Initialize Context-First in an existing project by creating `.contextrc.json`. |
-| `context-cli create:orchestrator` | Create a new orchestrator repository from a template with all necessary structure. |
-| `context-cli add:repo` | Add a new code repository to `context-manifest.json` interactively. |
-| `context-cli add:repo-metaspec` | Add or update the MetaSpecs repository in `context-manifest.json`. |
-| `context-cli config:setup` | Interactively configure `ai.properties.md` for local development. |
+|---------|-------------|
+| `create:orchestrator` | Create new orchestrator repository |
+| `config:setup` | Configure local environment (`ai.properties.md`) |
+| `add:repo` | Add repository to manifest |
+| `add:repo-metaspec` | Add MetaSpecs repository |
+| `init` | Initialize Context-First in existing project |
 ### Workspace Commands
 | Command | Description |
-| :--- | :--- |
-| `context-cli feature start <issue-id>` | Create a new feature workspace with isolated git worktrees. |
-| `context-cli feature list` | List all active feature workspaces on your machine. |
-| `context-cli feature switch <issue-id>` | Get the command to switch to an existing feature workspace. |
-| `context-cli feature merge <issue-id>` | Merge feature branch into target branch, push changes, and clean up workspace. |
-| `context-cli feature end <issue-id>` | Archive and clean up a completed feature workspace. |
+|---------|-------------|
+| `feature start <id>` | Create isolated workspace with worktrees |
+| `feature list` | List all active workspaces |
+| `feature switch <id>` | Get command to switch workspace |
+| `feature merge <id>` | Merge feature and clean up |
+| `feature end <id>` | Clean up workspace without merging |
-### Diagnostic Commands
+### Utility Commands
 | Command | Description |
-| :--- | :--- |
-| `context-cli doctor` | Check environment and configuration for issues. |
-| `context-cli status` | Show detailed status of the current workspace. |
+|---------|-------------|
+| `status` | Show workspace status |
+| `doctor` | Check environment health |
+| `update:commands` | Update AI command templates |
 ---
-## 🚀 Getting Started: The 5-Minute Workflow
-The primary workflow is designed to be simple and centralized within the Orchestrator.
+## Workflow Guide
-### Step 1: Create Your Orchestrator
+### Initial Setup (Once Per Project)
-This is your project's "home base". It defines your development process and the repositories involved.
+#### Step 1: Create Orchestrator
 ```bash
-# Run this once per project ecosystem
 npx context-first-cli@latest create:orchestrator
 ```
-This command interactively sets up your orchestrator, which includes:
--   `.contextrc.json`: A file that makes the orchestrator self-aware, so you can run all commands from here.
--   `context-manifest.json`: Defines all repositories in your project.
--   `.claude/commands/`: Pre-built command templates for your AI assistant.
--   `ai.properties.md`: A template for your local configuration (which is gitignored).
+**Prompts**:
+- Project name
+- Description
+- MetaSpecs repository URL (optional)
-### Step 2: Configure Your Local Environment
+**Creates**:
+```
+my-project-orchestrator/
+├── .contextrc.json
+├── context-manifest.json
+├── .claude/commands/
+└── ai.properties.md (template)
+```
-Navigate into the new orchestrator directory and tell the CLI where your code is located.
+#### Step 2: Configure Local Environment
 ```bash
-cd your-orchestrator-name/
+cd my-project-orchestrator/
 npx context-first-cli@latest config:setup
 ```
-This will ask for your **`base_path`**, which is the absolute path to the folder where you keep all your git repositories (e.g., `~/workspace` or `~/dev`). It also asks if you want to enable `auto_clone`.
+**Prompts**:
+- `base_path`: Where your repositories live (e.g., `~/dev`)
+- `auto_clone`: Automatically clone missing repos?
+- Task manager: Jira, Linear, GitHub, or none
-### Step 3: Add Your Repositories
+**Creates**: `ai.properties.md` with your local settings
-Now, define the repositories that make up your project.
+#### Step 3: Add Repositories
 ```bash
-# Still inside the orchestrator directory
 npx context-first-cli@latest add:repo
 ```
-Run this command for each repository (e.g., `backend`, `frontend`, `admin`). It will interactively ask for the repository's ID, Git URL, and role, and save it to `context-manifest.json`.
+**Prompts**:
+- Repository folder name (e.g., `backend`)
+- Git URL
+- Role: `backend`, `frontend`, `metaspecs`, or `other`
+- Description
-### Step 4: Start a Feature
+**Repeat** for each repository in your project.
-That's it for setup! Now you can start working on a feature. **From the orchestrator directory**, run:
+#### Step 4: Commit Orchestrator
 ```bash
-npx context-first-cli@latest feature start <issue-id>
-# Example: npx context-first-cli@latest feature start FIN-123
+git add .
+git commit -m "feat: setup orchestrator"
+git remote add origin <your-orchestrator-repo-url>
+git push -u origin main
 ```
-This command will:
-1.  Read your `context-manifest.json`.
-2.  Look for your repositories in the `base_path` you configured.
-3.  If a repository isn't found and `auto_clone` is true, it will clone it for you.
-4.  Create a new, isolated workspace in the orchestrator (e.g., `orchestrator/.sessions/FIN-123/`).
-5.  Use `git worktree` to efficiently check out a new feature branch for each selected repository into the workspace.
-6.  **Generate a `docker-compose.yml`** with dynamic ports based on the issue number (e.g., FIN-11 → backend:3011, frontend:8011, postgres:5411).
+---
+### Daily Development
-Your isolated, multi-repo development environment is ready, organized within your orchestrator!
+#### Start Feature
-**Running Services:**
 ```bash
-cd orchestrator/.sessions/FIN-123
-docker-compose up -d  # Start all services
-# Access: Backend at http://localhost:3123, Frontend at http://localhost:8123
-docker-compose down   # Stop all services
+# From orchestrator directory
+npx context-first-cli@latest feature start FIN-123
 ```
-### Step 5: Manage Your Workspaces
+**What happens**:
+1. Creates `.sessions/FIN-123/`
+2. Creates git worktrees for each repo
+3. Generates `docker-compose.yml` with ports 3123, 8123, 5523, 6423
+4. Ready to work!
+#### Enter Workspace
 ```bash
-# List all active workspaces
-npx context-first-cli@latest feature list
+cd .sessions/FIN-123
+```
-# Get the command to switch to a workspace
-npx context-first-cli@latest feature switch FIN-123
-# Then run the displayed command: cd orchestrator/.sessions/FIN-123
+#### Start Services (Optional)
-# Check the status of your current workspace
-cd orchestrator/.sessions/FIN-123/
-npx context-first-cli@latest status
+```bash
+docker-compose up -d
+```
-# Merge feature and clean up workspace
-npx context-first-cli@latest feature merge FIN-123
-# This will:
-# 1. Merge feature/FIN-123 into main (or specified target branch)
-# 2. Push changes to remote
-# 3. Delete feature branch
-# 4. Clean up workspace
+**Access**:
+- Backend: `http://localhost:3123`
+- Frontend: `http://localhost:8123`
+- Postgres: `localhost:5523`
+- Redis: `localhost:6423`
-# Or manually clean up without merging
-npx context-first-cli@latest feature end FIN-123
+#### Work on Feature
+```bash
+# Open in editor
+code .
+# Use AI commands (if configured)
+/start    # Create context.md and architecture.md
+/plan     # Create plan.md
+/work     # Implement feature
+/pre-pr   # Review before PR
+/pr       # Create pull request
 ```
-**Merge Options**:
+#### Stop Services
 ```bash
-# Merge into a different branch
-npx context-first-cli@latest feature merge FIN-123 --target-branch develop
+docker-compose down
+```
-# Merge without pushing (for manual review)
-npx context-first-cli@latest feature merge FIN-123 --no-push
+#### Finish Feature
-# Keep workspace after merge (for reference)
-npx context-first-cli@latest feature merge FIN-123 --keep-workspace
+**Option 1: Merge via CLI**
+```bash
+# From orchestrator directory
+npx context-first-cli@latest feature merge FIN-123
+```
-# Force merge without confirmation
-npx context-first-cli@latest feature merge FIN-123 --force
+**Option 2: Merge via GitHub + Clean Up**
+```bash
+# 1. Create PR via /pr command or manually
+# 2. Merge PR on GitHub
+# 3. Clean up workspace
+npx context-first-cli@latest feature end FIN-123
 ```
 ---
-## 🏗️ Architecture Overview
+## Docker Support
+### Automatic Generation
-```mermaid
-graph TD
-    subgraph User Machine
-        Dev[Developer] -->|uses| CLI[context-cli]
-    end
+When you run `feature start`, the CLI generates `docker-compose.yml` with:
-    subgraph Project Setup
-        CLI -->|reads| Config[.contextrc.json]
-        Config -->|points to| Orchestrator
-    end
+- **Backend** (if `role: "backend"` exists)
+- **Frontend** (if `role: "frontend"` exists)
+- **PostgreSQL** (always included)
+- **Redis** (always included)
-    subgraph Orchestrator [Orchestrator Repository]
-        style Orchestrator fill:#cde,stroke:#333,stroke-width:2px
-        Manifest[context-manifest.json<br/>Repository definitions]
-        Commands[.claude/commands/<br/>AI command definitions]
-        Props[ai.properties.md<br/>Local configuration]
-    end
+### Dynamic Ports
-    subgraph Workspace [Feature Workspace: FIN-123]
-        style Workspace fill:#f9f,stroke:#333,stroke-width:2px
-        WT1[metaspecs/<br/>git worktree]
-        WT2[backend/<br/>git worktree]
-        WT3[frontend/<br/>git worktree]
-    end
+Ports are calculated from issue number:
-    CLI -->|reads| Manifest
-    CLI -->|creates/manages| Workspace
 ```
+FIN-11:  Backend 3011, Frontend 8011, Postgres 5411, Redis 6311
+FIN-123: Backend 3123, Frontend 8123, Postgres 5523, Redis 6423
+```
+**Benefit**: Run multiple workspaces simultaneously without conflicts!
-This structure ensures a clean separation of concerns:
+### Configuration
--   **The CLI** is the universal engine that works for any project
--   **The Orchestrator** defines the process and ecosystem for a specific project
--   **The Workspace** is the temporary, isolated environment where work happens
+Edit `ai.properties.md` to customize base ports:
+```markdown
+## Docker Configuration
+docker.backend_base_port=3000
+docker.frontend_base_port=8000
+docker.postgres_base_port=5400
+docker.redis_base_port=6300
+```
+### Example `docker-compose.yml`
+```yaml
+version: '3.8'
+services:
+  backend:
+    build: ./backend
+    ports:
+      - "3011:3000"
+    environment:
+      - DATABASE_URL=postgresql://user:password@postgres:5432/app
+    networks:
+      - fin-11-network
+  frontend:
+    build: ./frontend
+    ports:
+      - "8011:8080"
+    environment:
+      - VITE_API_URL=http://localhost:3011
+    networks:
+      - fin-11-network
+  postgres:
+    image: postgres:15-alpine
+    ports:
+      - "5411:5432"
+    networks:
+      - fin-11-network
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6311:6379"
+    networks:
+      - fin-11-network
+networks:
+  fin-11-network:
+```
 ---
-## 📝 Example: Complete Setup for a New Project
+## Architecture
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      Developer Machine                       │
+│                                                               │
+│  ┌───────────────┐                                           │
+│  │ context-cli   │  (Universal CLI)                          │
+│  └───────┬───────┘                                           │
+│          │                                                    │
+│          ├─────────────────────────────────────────┐         │
+│          │                                         │         │
+│  ┌───────▼────────────────────────┐       ┌───────▼─────┐   │
+│  │   Orchestrator Repository      │       │  Workspaces │   │
+│  │                                 │       │             │   │
+│  │  • context-manifest.json        │       │  FIN-11/    │   │
+│  │  • .claude/commands/            │       │  FIN-12/    │   │
+│  │  • ai.properties.md             │       │  FIN-13/    │   │
+│  └─────────────────────────────────┘       └─────────────┘   │
+│                                                               │
+└───────────────────────────────────────────────────────────────┘
+┌─────────────────────────────────────────────────────────────┐
+│                    Main Repositories                         │
+│                                                               │
+│  ~/dev/backend/     (main branch)                            │
+│  ~/dev/frontend/    (main branch)                            │
+│  ~/dev/metaspecs/   (main branch)                            │
+│                                                               │
+└─────────────────────────────────────────────────────────────┘
+```
+**Flow**:
+1. CLI reads orchestrator configuration
+2. Creates workspace with worktrees
+3. Worktrees link to main repositories
+4. Developer works in isolated workspace
+5. Changes pushed to main repositories
+---
+## Examples
+### Example 1: Complete Setup
 ```bash
-# 1. Create the orchestrator (once per project)
+# Create orchestrator
 npx context-first-cli@latest create:orchestrator
-# Follow prompts: name, description, metaspecs URL...
+# Name: my-saas-orchestrator
+# Description: SaaS project orchestrator
-# 2. Enter the orchestrator and configure your local environment
+# Configure
 cd my-saas-orchestrator/
 npx context-first-cli@latest config:setup
 # Base path: ~/dev
 # Auto-clone: Yes
+# Task manager: Jira
+# Jira site: https://mycompany.atlassian.net
+# Jira project: SAAS
-# 3. Add all your project's repositories to the manifest
+# Add repositories
 npx context-first-cli@latest add:repo
-# ID: backend, URL: git@github.com:myorg/my-saas-backend.git
+# Folder name: my-saas-backend
+# URL: git@github.com:myorg/my-saas-backend.git
+# Role: backend
 npx context-first-cli@latest add:repo
-# ID: frontend, URL: git@github.com:myorg/my-saas-frontend.git
+# Folder name: my-saas-frontend
+# URL: git@github.com:myorg/my-saas-frontend.git
+# Role: frontend
-# 4. Commit and push your orchestrator setup
+# Commit
 git add .
-git commit -m "feat: configure orchestrator with project repositories"
-git remote add origin git@github.com:myorg/my-saas-orchestrator.git
+git commit -m "feat: setup orchestrator"
 git push -u origin main
+```
+### Example 2: Working on Feature
-# 5. Start working on a feature!
-# (Make sure your repos like 'my-saas-backend' exist in '~/dev' or enable auto_clone)
-npx context-first-cli@latest feature start PROJ-123
+```bash
+# Start feature
+npx context-first-cli@latest feature start SAAS-456
-# 6. Switch to the new workspace directory to begin work
-cd .sessions/PROJ-123/
+# Enter workspace
+cd .sessions/SAAS-456
+# Start services
+docker-compose up -d
+# Work
 code .
-# All selected repositories are now checked out here as worktrees!
+# Stop services
+docker-compose down
+# Merge and clean up
+cd ../..
+npx context-first-cli@latest feature merge SAAS-456
+```
+### Example 3: Parallel Development
+```bash
+# Developer working on two features simultaneously
+# Feature 1
+npx context-first-cli@latest feature start FIN-11
+cd .sessions/FIN-11
+docker-compose up -d
+# Backend at http://localhost:3011
+# Feature 2 (in another terminal)
+cd ~/my-orchestrator
+npx context-first-cli@latest feature start FIN-12
+cd .sessions/FIN-12
+docker-compose up -d
+# Backend at http://localhost:3012
+# Both running simultaneously! No conflicts!
+```
+---
+## Troubleshooting
+### Issue: "Workspace already exists"
+**Cause**: You already created a workspace for this issue.
+**Solution**:
+```bash
+# Option 1: Use existing workspace
+cd .sessions/FIN-123
+# Option 2: Clean up and recreate
+npx context-first-cli@latest feature end FIN-123
+npx context-first-cli@latest feature start FIN-123
+```
+### Issue: "Repository not found"
+**Cause**: Repository doesn't exist in `base_path`.
+**Solution**:
+```bash
+# Option 1: Clone manually
+cd ~/dev
+git clone <repo-url> <repo-folder-name>
+# Option 2: Enable auto_clone
+# Edit ai.properties.md:
+auto_clone=true
+```
+### Issue: "Branch already in use"
+**Cause**: Main repository is on the feature branch.
+**Solution**:
+```bash
+# Go to main repository
+cd ~/dev/<repo-name>
+# Switch to main branch
+git checkout main
+# Try again
+cd ~/orchestrator
+npx context-first-cli@latest feature start FIN-123
+```
+### Issue: "Port already in use"
+**Cause**: Another workspace with same issue number is running.
+**Solution**:
+```bash
+# Stop other workspace
+cd .sessions/FIN-123
+docker-compose down
+# Or use different issue number
+```
+### Issue: "Docker containers not stopping"
+**Cause**: `feature end` failed to stop containers.
+**Solution**:
+```bash
+# Manually stop containers
+cd .sessions/FIN-123
+docker-compose down -v
+# Then clean up workspace
+cd ../..
+npx context-first-cli@latest feature end FIN-123
 ```
 ---
-## 📝 License
+## Advanced Usage
+### Custom Docker Ports
+Edit `ai.properties.md`:
-MIT
+```markdown
+docker.backend_base_port=4000
+docker.frontend_base_port=9000
+docker.postgres_base_port=6000
+docker.redis_base_port=7000
+```
+Now FIN-11 will use ports 4011, 9011, 6011, 7011.
+### Merge Options
+```bash
+# Merge to develop instead of main
+npx context-first-cli@latest feature merge FIN-123 --target-branch develop
+# Merge without pushing (review first)
+npx context-first-cli@latest feature merge FIN-123 --no-push
+# Keep workspace after merge
+npx context-first-cli@latest feature merge FIN-123 --keep-workspace
+# Force merge without confirmation
+npx context-first-cli@latest feature merge FIN-123 --force
+```
+### Update Commands
+When CLI is updated, refresh AI command templates:
+```bash
+cd ~/orchestrator
+npx context-first-cli@latest update:commands
+```
+---
+## Contributing
+Contributions are welcome! Please open an issue or PR on [GitHub](https://github.com/thatix-io/context-first-cli).
+---
+## License
+MIT © [Thiago Abreu](https://github.com/thatix-io)
 ---
-## 🔗 Links
+## Links
+- **NPM**: https://www.npmjs.com/package/context-first-cli
+- **GitHub**: https://github.com/thatix-io/context-first-cli
+- **Issues**: https://github.com/thatix-io/context-first-cli/issues
+- **Documentation**: https://github.com/thatix-io/context-first-cli#readme
+---
-- **NPM Package**: https://www.npmjs.com/package/context-first-cli
-- **GitHub Repository**: https://github.com/thatix-io/context-first-cli
-- **Issues & Support**: https://github.com/thatix-io/context-first-cli/issues
+**Made with ❤️ for developers who value context and efficiency.**

package/dist/templates/commands/engineer/work.md CHANGED Viewed

@@ -128,30 +128,34 @@ Refs: <ISSUE-ID>"
 **Tipos de commit**: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`
-### 5. Documentação da Sessão
+### 5. Atualização do Plan.md
-Atualize `./.sessions/<ISSUE-ID>/work.md`:
+**A CADA tarefa completada**, atualize `./.sessions/<ISSUE-ID>/plan.md`:
 ```markdown
-# [Título da Feature] - Trabalho Executado
-## [Data/Hora] - [Descrição da Unidade]
-### Repositórios Modificados
-- **repo-1**: [Arquivos modificados e o que foi feito]
-- **repo-2**: [Arquivos modificados e o que foi feito]
-### Decisões Tomadas
-- [Decisão 1 e justificativa]
-- [Decisão 2 e justificativa]
-### Testes Adicionados
-- [Descrição dos testes]
-### Próxima Unidade
-- [O que será feito a seguir]
+#### 1.1 - [Nome da Tarefa] [Completada ✅]
+- [Detalhe 1]
+- [Detalhe 2]
+- [Detalhe 3]
+**Arquivos**:
+- `path/to/file1.ts` ✅
+- `path/to/file2.vue` ✅
+**Testes**:
+- Unit test: [Descrição] ✅
+- Integration test: [Descrição] ✅
+**Comentários**:
+- Decisão: [Explicação de decisão técnica importante]
+- Aprendizado: [Algo aprendido durante implementação]
 ```
+**Marque status das tarefas**:
+- `[Não Iniciada ⏳]` - Tarefa ainda não começou
+- `[Em Progresso ⏰]` - Tarefa sendo trabalhada agora
+- `[Completada ✅]` - Tarefa finalizada e validada
 ## 🔍 Checklist de Qualidade
 Antes de considerar a unidade completa:
@@ -160,7 +164,7 @@ Antes de considerar a unidade completa:
 - [ ] Linting/formatação OK
 - [ ] Documentação atualizada (se necessário)
 - [ ] Commit realizado em todos os repos afetados
-- [ ] Sessão documentada
+- [ ] `plan.md` atualizado com progresso e comentários
 ## ⚠️ Princípio Jidoka

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "context-first-cli",
-  "version": "1.8.0",
+  "version": "1.8.2",
   "description": "A generic CLI to manage the Context-First development methodology across any project.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/templates/commands/engineer/work.md CHANGED Viewed

@@ -128,30 +128,34 @@ Refs: <ISSUE-ID>"
 **Tipos de commit**: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`
-### 5. Documentação da Sessão
+### 5. Atualização do Plan.md
-Atualize `./.sessions/<ISSUE-ID>/work.md`:
+**A CADA tarefa completada**, atualize `./.sessions/<ISSUE-ID>/plan.md`:
 ```markdown
-# [Título da Feature] - Trabalho Executado
-## [Data/Hora] - [Descrição da Unidade]
-### Repositórios Modificados
-- **repo-1**: [Arquivos modificados e o que foi feito]
-- **repo-2**: [Arquivos modificados e o que foi feito]
-### Decisões Tomadas
-- [Decisão 1 e justificativa]
-- [Decisão 2 e justificativa]
-### Testes Adicionados
-- [Descrição dos testes]
-### Próxima Unidade
-- [O que será feito a seguir]
+#### 1.1 - [Nome da Tarefa] [Completada ✅]
+- [Detalhe 1]
+- [Detalhe 2]
+- [Detalhe 3]
+**Arquivos**:
+- `path/to/file1.ts` ✅
+- `path/to/file2.vue` ✅
+**Testes**:
+- Unit test: [Descrição] ✅
+- Integration test: [Descrição] ✅
+**Comentários**:
+- Decisão: [Explicação de decisão técnica importante]
+- Aprendizado: [Algo aprendido durante implementação]
 ```
+**Marque status das tarefas**:
+- `[Não Iniciada ⏳]` - Tarefa ainda não começou
+- `[Em Progresso ⏰]` - Tarefa sendo trabalhada agora
+- `[Completada ✅]` - Tarefa finalizada e validada
 ## 🔍 Checklist de Qualidade
 Antes de considerar a unidade completa:
@@ -160,7 +164,7 @@ Antes de considerar a unidade completa:
 - [ ] Linting/formatação OK
 - [ ] Documentação atualizada (se necessário)
 - [ ] Commit realizado em todos os repos afetados
-- [ ] Sessão documentada
+- [ ] `plan.md` atualizado com progresso e comentários
 ## ⚠️ Princípio Jidoka