context-first-cli 1.2.1 → 1.2.2

package/README.md

@@ -12,8 +12,8 @@ This CLI is built on three core concepts that enable scalable, parallel, and con
 
 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:
 
--   **Command Definitions**: Markdown files (`/commands/definitions`) that instruct an AI (like Claude) on the purpose and logic of each step in your process (e.g., `/work`, `/spec`).
--   **Repository Manifest**: A `context-manifest.json` file that maps out your entire project ecosystem, defining all repositories and their relationships.
+-   **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.
 
 ### 2. Feature Workspaces
@@ -25,7 +25,7 @@ To enable parallel development without conflicts, the CLI uses **Feature Workspa
 
 ### 3. The Agnostic CLI (`context-cli`)
 
-This is the tool you install on your machine. It's completely project-agnostic. You can use the same CLI to manage desenvolvimento para o `credit-flow`, `orca-sonhos`, ou qualquer outro projeto.
+This is the tool you install on your machine. It's completely project-agnostic. You can use the same CLI to manage any project.
 
 -   **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.
@@ -33,73 +33,152 @@ This is the tool you install on your machine. It's completely project-agnostic.
 
 ---
 
-## ⚙️ Getting Started
-
-### Installation
+## 📦 Installation
 
 Install the CLI globally on your machine via NPM.
 
 ```bash
 npm install -g context-first-cli
 ```
-*(Note: Once published to NPM)*
 
-### Initialization
+---
+
+## 📋 Commands Reference
 
-There are two main scenarios for getting started.
+### Setup Commands
 
-**Scenario 1: You have an existing project and want to adopt Context-First.**
+| 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`. |
 
-1.  Navigate to the root of one of your application repositories.
-2.  Run the `init` command:
-    ```bash
-    context-cli init
-    ```
-3.  The CLI will ask you for the Git URL of your Orchestrator repository and your preferred AI provider. It will then create a `.contextrc.json` file to link this project to its orchestrator.
+### Workspace Commands
 
-**Scenario 2: You are starting a new project ecosystem from scratch.**
+| 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:end <issue-id>` | Archive and clean up a completed feature workspace. |
 
-1.  Create a new, empty directory for your orchestrator.
-2.  Run the `scaffold:orchestrator` command:
-    ```bash
-    context-cli scaffold:orchestrator
-    ```
-3.  This will generate a complete, ready-to-use Orchestrator repository with template files and a standard directory structure.
+### Diagnostic Commands
+
+| Command | Description |
+| :--- | :--- |
+| `context-cli doctor` | Check environment and configuration for issues. |
+| `context-cli status` | Show detailed status of the current workspace. |
 
 ---
 
-## 📋 Main Commands
+## 🚀 Getting Started: Complete Workflow
 
-Below is an overview of the primary commands available in the CLI.
+### Step 1: Create a New Orchestrator
 
-| Command | Description |
-| :--- | :--- |
-| `context-cli init` | **Initializes** a project by creating a `.contextrc.json` file that links it to an orchestrator. |
-| `context-cli scaffold:orchestrator` | **Creates a new** Orchestrator repository from a best-practice template. |
-| `context-cli feature:start <issue-id>` | **Starts a new feature** by creating an isolated workspace with all necessary repositories checked out via `git worktree`. |
-| `context-cli feature:list` | **Lists all** active feature workspaces on your machine. |
-| `context-cli feature:end <issue-id>` | **Cleans up** a completed feature by removing the worktrees and archiving the workspace. |
-| `context-cli work "<message>"` | **Records a unit of work** within the current workspace, typically performing a `git commit`. |
-| `context-cli spec` | **Generates specifications** (e.g., a PRD) for the feature in the current workspace. |
-| `context-cli doctor` | **Checks your environment** to ensure all configurations, paths, and dependencies are correctly set up. |
+First, create a central orchestrator for your project ecosystem.
+
+```bash
+npx context-first-cli@latest create:orchestrator
+```
+
+This will guide you through an interactive setup:
+1.  **Project name** (e.g., `my-project-orchestrator`)
+2.  **Project description**
+3.  **MetaSpecs repository URL** (Git URL of your specifications repository)
+4.  **Task manager** (Jira, Linear, GitHub, or None)
+5.  **Initialize Git** (optional: create initial commit)
+
+The orchestrator will be created with:
+- `.claude/commands/` - 11 command definitions for AI (warm-up, products, engineer, quality)
+- `context-manifest.json` - Repository manifest with your MetaSpecs already configured
+- `ai.properties.md` - Configuration template (gitignored, each dev has their own)
+- `.sessions/` - Session data directory (gitignored)
+
+### Step 2: Add Application Repositories
+
+Navigate into your orchestrator directory and add your application repositories.
+
+```bash
+cd my-project-orchestrator/
+
+# Add your backend repository
+npx context-first-cli@latest add:repo
+# You'll be asked for: ID, URL, description, role, dependencies
+
+# Add your frontend repository
+npx context-first-cli@latest add:repo
+
+# Add more repositories as needed
+npx context-first-cli@latest add:repo
+```
+
+Each repository will be added to `context-manifest.json` with its configuration.
+
+### Step 3: Configure Local Paths
+
+Edit `ai.properties.md` in your orchestrator to set up local paths and credentials:
+
+```markdown
+# Paths dos Projetos
+base_path=/path/to/your/workspace
+meta_specs_path=/path/to/your/meta-specs
+backend_path=/path/to/your/backend
+frontend_path=/path/to/your/frontend
+
+# Task Manager Configuration
+task_management_system=jira
+jira_site=https://your-org.atlassian.net
+...
+```
+
+**Note**: This file is gitignored because it contains local paths specific to each developer.
 
-### Example Workflow
+### Step 4: Initialize Your Application Repositories
+
+For each of your application repositories, run `init` to link it to the orchestrator.
 
 ```bash
-# 1. Start work on a new feature from Jira
-context-cli feature:start FIN-123
+cd /path/to/your/backend/
+npx context-first-cli@latest init
+```
 
-# 2. Navigate into the newly created workspace
-cd workspaces/FIN-123
+This will ask for:
+1.  The Git URL of your orchestrator repository
+2.  Your AI provider (Claude, Cursor, etc.)
 
-# 3. Open the workspace in your favorite editor
-code .
+A `.contextrc.json` file will be created linking this project to the orchestrator.
 
-# 4. Make code changes, then record your work
-context-cli work "feat(api): add validation to user endpoint"
+### Step 5: Start Working on a Feature
 
-# 5. When done, create pull requests
-context-cli pr
+Now you can start working on a feature from any of your configured repositories.
+
+```bash
+cd /path/to/your/backend/
+npx context-first-cli@latest feature:start FIN-123
+```
+
+This will:
+1.  Create a new workspace directory (e.g., `~/workspaces/FIN-123/`)
+2.  Use `git worktree` to check out branches for all required repositories
+3.  Set up the workspace with proper structure
+
+### Step 6: Manage Your Workspaces
+
+```bash
+# List all active workspaces
+npx context-first-cli@latest feature:list
+
+# Get the command to switch to a workspace
+npx context-first-cli@latest feature:switch FIN-123
+# Then run the displayed command: cd ~/workspaces/FIN-123
+
+# Check the status of your current workspace
+cd ~/workspaces/FIN-123/
+npx context-first-cli@latest status
+
+# Clean up a finished workspace
+npx context-first-cli@latest feature:end FIN-123
 ```
 
 ---
@@ -108,37 +187,90 @@ context-cli pr
 
 ```mermaid
 graph TD
-    subgraph User (Any OS)
-        Dev[Developer] -->|uses| CLI
-    end
-
-    subgraph CLI (context-cli NPM package)
-        CLI[CLI Commands] -->|reads| Config
-        CLI -->|executes logic on| Workspace
+    subgraph User Machine
+        Dev[Developer] -->|uses| CLI[context-cli]
     end
 
     subgraph Project Setup
-        Config[.contextrc.json] -->|points to| OrchestratorRepo
+        CLI -->|reads| Config[.contextrc.json]
+        Config -->|points to| Orchestrator
     end
 
-    subgraph OrchestratorRepo [Orchestrator Repository]
-        style OrchestratorRepo fill:#cde,stroke:#333,stroke-width:2px
-        Manifest[context-manifest.json]
-        Defs[commands/definitions/*.md]
+    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
 
-    subgraph Workspace [Feature Workspace]
+    subgraph Workspace [Feature Workspace: FIN-123]
         style Workspace fill:#f9f,stroke:#333,stroke-width:2px
-        Worktree1[Worktree of Repo A]
-        Worktree2[Worktree of Repo B]
+        WT1[metaspecs/<br/>git worktree]
+        WT2[backend/<br/>git worktree]
+        WT3[frontend/<br/>git worktree]
     end
 
-    CLI -- "Reads Manifest from" --> Manifest
-    CLI -- "Creates/Manages" --> Workspace
+    CLI -->|reads| Manifest
+    CLI -->|creates/manages| Workspace
 ```
 
 This structure ensures a clean separation of concerns:
 
--   **The CLI** is the universal engine.
--   **The Orchestrator Repo** defines the process for a specific project.
--   **The Workspace** is the temporary, isolated environment where work actually happens.
+-   **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
+
+---
+
+## 📝 Example: Complete Setup for a New Project
+
+```bash
+# 1. Create orchestrator
+npx context-first-cli@latest create:orchestrator
+# Name: my-saas-orchestrator
+# MetaSpecs URL: git@github.com:myorg/my-saas-metaspecs.git
+
+# 2. Add repositories
+cd my-saas-orchestrator/
+npx context-first-cli@latest add:repo
+# ID: backend, URL: git@github.com:myorg/my-saas-backend.git
+
+npx context-first-cli@latest add:repo
+# ID: frontend, URL: git@github.com:myorg/my-saas-frontend.git
+
+npx context-first-cli@latest add:repo
+# ID: admin, URL: git@github.com:myorg/my-saas-admin.git
+
+# 3. Configure local paths
+nano ai.properties.md
+# Edit paths to match your local setup
+
+# 4. Push orchestrator to Git
+git remote add origin git@github.com:myorg/my-saas-orchestrator.git
+git push -u origin main
+
+# 5. Initialize each application repo
+cd ~/projects/my-saas-backend/
+npx context-first-cli@latest init
+# Orchestrator URL: git@github.com:myorg/my-saas-orchestrator.git
+# AI Provider: claude
+
+# 6. Start working on a feature
+npx context-first-cli@latest feature:start PROJ-123
+cd ~/workspaces/PROJ-123/
+# All repositories are now checked out and ready to work!
+```
+
+---
+
+## 📝 License
+
+MIT
+
+---
+
+## 🔗 Links
+
+- **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

package/package.json

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