@fiftth/fiftth-cli 1.0.1 → 1.1.1

package/README.md

@@ -1,29 +1,112 @@
 # Fiftth CLI
 
 ```text
-███████╗██╗███████╗████████╗████████╗██╗  ██╗
-██╔════╝██║██╔════╝╚══██╔══╝╚══██╔══╝██║  ██║
-█████╗  ██║█████╗     ██║      ██║   ███████║
-██╔══╝  ██║██╔══╝     ██║      ██║   ██╔══██║
-██║     ██║██║        ██║      ██║   ██║  ██║
-╚═╝     ╚═╝╚═╝        ╚═╝      ╚═╝   ╚═╝  ╚═╝
+. . . ....
 ```
 
 The official CLI for [Fiftth](https://fiftth.com).
 
-Built for humans, AI agents, and CI/CD pipelines.
-The "fiftth" symphony of Software Engineering. Start orchestrating your engineering workflows. 
+Fiftth CLI is the entrypoint for the full Fiftth execution flow: authenticate, select a workspace, register local repositories, validate planning context, recover task-linked branches, and launch Nexus orchestration for agent execution.
 
-Fiftth CLI helps your team authenticate, select a workspace, sync tasks, and checkout the right branch for each task-linked repository.
+## How The Flow Works
 
-## Features
+### . . . .... 1. Shell setup
 
-- Command aliases: `fiftth` and `ftt`
+You install the CLI, authenticate with Fiftth, select a workspace, choose a default model, and register the local repositories that belong to your tasks.
+
+This can be done from any directory. The CLI persists its own configuration and repository mappings, so `ftt checkout` does not require you to be inside a git repository.
+
+### . . . .... 2. Planning flow
+
+Inside a repository, `ftt planning-context` validates whether the current repo is actually linked to the selected task before you create or refine a PRD.
+
+The typical planning sequence is:
+
+1. `grill-me` to pressure-test the design
+2. `write-prd` to produce the PRD
+3. `prd-to-issues` to split the PRD into runnable GitHub issues with priority and dependency metadata
+
+### . . . .... 3. Checkout flow
+
+```text
+  ftt checkout
+	  |
+	  v
+  +-----------------------+
+  | resolve active task   |
+  +-----------------------+
+	  |
+	  v
+  +-----------------------+
+  | load mapped repos     |
+  +-----------------------+
+	  |
+	  v
+  +-----------------------+
+  | validate repo paths   |
+  | git state + PRDs      |
+  +-----------------------+
+	  |
+	  v
+  +-----------------------+
+  | move task to          |
+  | IN_PROGRESS           |
+  +-----------------------+
+	  |
+	  v
+  +-----------------------+
+  | wait for target       |
+  | branches              |
+  +-----------------------+
+	  |
+	  v
+  +-----------------------+
+  | start Nexus           |
+  | orchestration         |
+  +-----------------------+
+```
+
+When you run `ftt checkout`, the CLI:
+
+1. Resolves the selected task from the current workspace
+2. Loads the locally mapped repositories for that task
+3. Verifies each mapped path exists, is a git repository, and has a clean working tree
+4. Validates that each linked repository has an unambiguous PRD for the task
+5. Moves the task to `IN_PROGRESS` when needed
+6. Polls execution stages until the target branches are available
+7. Starts Nexus to execute the agent pipeline against the recovered branches
+
+### . . . .... 4. Nexus orchestration
+
+Nexus lives under `.fiftthnexus/` and is started by `ftt checkout` after branch recovery.
+
+At runtime, Nexus:
+
+1. Uses `gh auth` from the host machine for GitHub access
+2. Ensures required GitHub labels exist in each repository
+3. Builds the `copilot-agent` Docker image automatically if it is missing
+4. Resolves the issue dependency graph for the selected PRD or task scope
+5. Creates isolated worktrees when worktree mode is enabled
+6. Runs the three-stage pipeline for each runnable issue in Docker
+7. Repeats until there are no runnable issues left or the queue is exhausted
+
+The three execution stages are:
+
+- `PLAN`: analyze the issue context and produce an execution plan
+- `IMPLEMENT`: apply the code changes in the isolated workspace
+- `REVIEW`: run a lightweight final review pass focused on concrete blockers
+
+## Requirements
+
+- Node.js 18 or newer
+- Git available in your shell
+- Docker available locally for checkout and Nexus execution
+- GitHub CLI (`gh`) authenticated for repositories that will run Nexus
 
 ## Install
 
 ```bash
-npm i -g @fiftth/fiftth-cli
+npm install -g @fiftth/fiftth-cli
 ```
 
 ### Local development link
@@ -41,41 +124,118 @@ fiftth --help
 ftt --help
 ```
 
+To remove the global development link later:
+
+```bash
+npm run unlink
+```
+
 ## Quick Start
 
-1. Authenticate
+1. Authenticate with Fiftth
 
 ```bash
 fiftth login
 ```
 
-2. Choose workspace
+For CI or non-interactive shells, you can pass a token directly:
+
+```bash
+fiftth login --token <token>
+```
+
+2. Choose a workspace
 
 ```bash
 fiftth use
 ```
 
-3. Add local repositories
+You can also switch directly by slug or name:
+
+```bash
+fiftth use my-workspace
+```
+
+3. Choose the default model used by checkout and Nexus
+
+```bash
+fiftth model
+```
+
+Or set it directly:
+
+```bash
+fiftth model gpt-5.4
+```
+
+4. Install the bundled planning skills for your preferred agent runtime
+
+```bash
+fiftth skills
+```
+
+This command prompts you to install `grill-me`, `write-prd`, and `prd-to-issues` into one of these user directories:
+
+The files are installed relative to the directory where you run the command:
+
+- GitHub Copilot: `./.github/agents`
+- Claude Code: `./claude/skills`
+
+5. Register the local repositories used by your task-linked execution flow
 
 ```bash
 fiftth repo add api ~/dev/api
 fiftth repo add mobile C:\Users\you\Desktop\Owner\repo
 ```
 
-4. Select task and list linked repositories
+6. If you are about to create or refine a PRD from inside a repository, validate planning context first
+
+```bash
+fiftth planning-context
+```
+
+7. Run checkout from any directory to start the orchestration flow
 
 ```bash
-fiftth tasks
+fiftth checkout
 ```
 
-5. Checkout task branch in a configured repository
+To target a specific task directly:
 
 ```bash
 fiftth checkout <taskId>
 ```
 
+To keep the main repository checkout untouched and let Nexus branch from a worktree instead:
+
+```bash
+fiftth checkout --worktree
+```
+
+To stream verbose Nexus logs during checkout:
+
+```bash
+fiftth checkout --verbose
+```
+
+8. If you need to verify GitHub authentication for Nexus on the host machine
+
+```bash
+gh auth status
+```
+
 ## Commands
 
+### General
+
+- `fiftth --help`
+- `fiftth --version`
+- `fiftth config`
+- `fiftth model`
+- `fiftth model <name>`
+- `fiftth skills`
+- `fiftth skills <agent>`
+
 ### Authentication
 
 - `fiftth login`
@@ -90,7 +250,6 @@ To use `fiftth login --token <token>`, you must first sign in on the [Fiftth](ht
 
 - `fiftth use`
 - `fiftth use <workspace>`
-- `fiftth use --list`
 
 ### Repository Registry
 
@@ -100,23 +259,55 @@ To use `fiftth login --token <token>`, you must first sign in on the [Fiftth](ht
 
 ### Tasks and Checkout
 
-- `fiftth tasks`
+- `fiftth planning-context`
+- `fiftth planning-context <taskId>`
+- `fiftth planning-context <taskId> --json`
+- `fiftth checkout`
 - `fiftth checkout <taskId>`
+- `fiftth checkout --worktree`
+- `fiftth checkout --verbose`
 
 ## Configuration
 
-Config is saved to:
+Main CLI configuration is saved to:
 
 - `~/.fiftth/config.json`
 
+The file stores the current host, access token, selected workspace, workspace id, and preferred model.
+
 Current defaults:
 
+- Host: `https://www.fiftth.com/api`
+- Model: `gpt-5.4`
+
+Supported model values:
+
+- `gpt-5.4`
+- `gpt-5.4-mini`
+- `gpt-5.3-codex`
+- `claude-sonnet-4.6`
+- `claude-opus-4.6`
+- `claude-haiku-4.5`
+
+To inspect the current resolved shell configuration:
+
+```bash
+fiftth config
+```
+
 ## Notes
 
-- `checkout` requires:
-  - selecting the task first (`fiftth tasks`)
-  - local repo mappings for linked repositories (`fiftth repo add ...`)
-  - a clean git working tree
+- `checkout` requires local repo mappings for linked repositories (`fiftth repo add ...`)
+- `checkout` requires a clean git working tree in every linked repository
+- `checkout` requires Docker available on the host machine
+- `checkout --verbose` keeps the normal preflight and then streams detailed Nexus logs once orchestration starts
+- `planning-context` is the safe preflight for skills and manual planning flows: it validates that the current git repository is one of the repositories linked to the selected task and exits non-zero when it is not
+- `planning-context` is the command that depends on the current directory being a git repository; `checkout` does not have that requirement
+- if no `taskId` is provided, `checkout` prompts for an active task interactively
+- with `checkout --worktree`, the CLI fetches the target branches, cleans up previous Nexus worktrees for the task, and leaves the main repo checkout unchanged before starting Nexus
+- after local checkout succeeds, `checkout` moves the task to `IN_PROGRESS`, polls `/api/tasks/:taskId/execution-stages` every 5 seconds, and starts Nexus once the target branches are available
+- `planning-context --json` is intended for agent and automation flows and exits with code `1` when the current repository is not part of the selected task
+- the orchestrator uses the host `gh` authentication state and injects that token into each isolated agent container
 
 ## License
 

package/dist/api/client.d.ts

@@ -1,6 +1,12 @@
+export interface Workspace {
+    id: string;
+    name: string;
+    slug: string;
+}
 export interface ApiClient {
     get<T>(endpoint: string): Promise<T>;
     post<T>(endpoint: string, body: unknown): Promise<T>;
+    getWorkspaces(): Promise<Workspace[]>;
 }
 export declare function createApiClient(): ApiClient;
 //# sourceMappingURL=client.d.ts.map

package/dist/api/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,SAAS;IACxB,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;IACpC,IAAI,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;CACrD;AAED,wBAAgB,eAAe,IAAI,SAAS,CAsB3C"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,SAAS;IACxB,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;IACpC,IAAI,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;IACpD,aAAa,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC,CAAA;CACtC;AAUD,wBAAgB,eAAe,IAAI,SAAS,CA0B3C"}

package/dist/api/client.js

@@ -1,13 +1,20 @@
 import axios from 'axios';
 import { loadConfig } from '../utils/config.js';
+import { getUserAgent } from '../utils/version.js';
+function buildAuthorizationHeader(token) {
+    if (!token) {
+        throw new Error('Not authenticated. Run fiftth login first.');
+    }
+    return `Bearer ${token}`;
+}
 export function createApiClient() {
     const config = loadConfig();
     const httpClient = axios.create({
         baseURL: config.host,
         headers: {
-            Authorization: `Bearer ${config.token}`,
+            Authorization: buildAuthorizationHeader(config.token),
             'Content-Type': 'application/json',
-            'User-Agent': 'fiftth-cli/0.1.0',
+            'User-Agent': getUserAgent(),
         },
     });
     return {
@@ -19,6 +26,10 @@ export function createApiClient() {
             const response = await httpClient.post(endpoint, body);
             return response.data;
         },
+        async getWorkspaces() {
+            const response = await httpClient.get('/workspaces');
+            return response.data;
+        },
     };
 }
 //# sourceMappingURL=client.js.map

package/dist/api/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAA6B,MAAM,OAAO,CAAA;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAO/C,MAAM,UAAU,eAAe;IAC7B,MAAM,MAAM,GAAG,UAAU,EAAE,CAAA;IAE3B,MAAM,UAAU,GAAkB,KAAK,CAAC,MAAM,CAAC;QAC7C,OAAO,EAAE,MAAM,CAAC,IAAI;QACpB,OAAO,EAAE;YACP,aAAa,EAAE,UAAU,MAAM,CAAC,KAAK,EAAE;YACvC,cAAc,EAAE,kBAAkB;YAClC,YAAY,EAAE,kBAAkB;SACjC;KACF,CAAC,CAAA;IAEF,OAAO;QACL,KAAK,CAAC,GAAG,CAAI,QAAgB;YAC3B,MAAM,QAAQ,GAAG,MAAM,UAAU,CAAC,GAAG,CAAI,QAAQ,CAAC,CAAA;YAClD,OAAO,QAAQ,CAAC,IAAI,CAAA;QACtB,CAAC;QACD,KAAK,CAAC,IAAI,CAAI,QAAgB,EAAE,IAAa;YAC3C,MAAM,QAAQ,GAAG,MAAM,UAAU,CAAC,IAAI,CAAI,QAAQ,EAAE,IAAI,CAAC,CAAA;YACzD,OAAO,QAAQ,CAAC,IAAI,CAAA;QACtB,CAAC;KACF,CAAA;AACH,CAAC"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAA6B,MAAM,OAAO,CAAA;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAclD,SAAS,wBAAwB,CAAC,KAAc;IAC9C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAA;IAC/D,CAAC;IAED,OAAO,UAAU,KAAK,EAAE,CAAA;AAC1B,CAAC;AAED,MAAM,UAAU,eAAe;IAC7B,MAAM,MAAM,GAAG,UAAU,EAAE,CAAA;IAE3B,MAAM,UAAU,GAAkB,KAAK,CAAC,MAAM,CAAC;QAC7C,OAAO,EAAE,MAAM,CAAC,IAAI;QACpB,OAAO,EAAE;YACP,aAAa,EAAE,wBAAwB,CAAC,MAAM,CAAC,KAAK,CAAC;YACrD,cAAc,EAAE,kBAAkB;YAClC,YAAY,EAAE,YAAY,EAAE;SAC7B;KACF,CAAC,CAAA;IAEF,OAAO;QACL,KAAK,CAAC,GAAG,CAAI,QAAgB;YAC3B,MAAM,QAAQ,GAAG,MAAM,UAAU,CAAC,GAAG,CAAI,QAAQ,CAAC,CAAA;YAClD,OAAO,QAAQ,CAAC,IAAI,CAAA;QACtB,CAAC;QACD,KAAK,CAAC,IAAI,CAAI,QAAgB,EAAE,IAAa;YAC3C,MAAM,QAAQ,GAAG,MAAM,UAAU,CAAC,IAAI,CAAI,QAAQ,EAAE,IAAI,CAAC,CAAA;YACzD,OAAO,QAAQ,CAAC,IAAI,CAAA;QACtB,CAAC;QACD,KAAK,CAAC,aAAa;YACjB,MAAM,QAAQ,GAAG,MAAM,UAAU,CAAC,GAAG,CAAc,aAAa,CAAC,CAAA;YACjE,OAAO,QAAQ,CAAC,IAAI,CAAA;QACtB,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/commands/checkout.d.ts

@@ -1,2 +1,7 @@
-export declare function checkoutCommand(taskId: string): Promise<void>;
+interface CheckoutOptions {
+    worktree?: boolean;
+    verbose?: boolean;
+}
+export declare function checkoutCommand(taskId?: string, options?: CheckoutOptions): Promise<void>;
+export {};
 //# sourceMappingURL=checkout.d.ts.map

package/dist/commands/checkout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"checkout.d.ts","sourceRoot":"","sources":["../../src/commands/checkout.ts"],"names":[],"mappings":"AAaA,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAuFnE"}
+{"version":3,"file":"checkout.d.ts","sourceRoot":"","sources":["../../src/commands/checkout.ts"],"names":[],"mappings":"AAmCA,UAAU,eAAe;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AA2KD,wBAAsB,eAAe,CACnC,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAgcf"}