nightshift-mcp 1.0.0 → 1.0.3

package/README.md

@@ -12,12 +12,17 @@ An MCP (Model Context Protocol) server that enables multi-agent communication an
 
 - **Multi-agent chat**: Structured messages with agent name, timestamp, type, and content
 - **Failover handling**: Seamless handoffs when an agent hits limits
-- **Ralph-style PRD management**: Work through user stories in prd.json
+- **Ralph-style PRD management**: Work through user stories in prd.json with Zod-validated schemas and helpful error messages
 - **Progress tracking**: Shared learnings via progress.txt
-- **Agent tracking**: See which agents are active and what they're working on
+- **Agent spawning & orchestration**: Spawn Claude, Codex, Gemini, or Vibe as subprocesses with full lifecycle tracking
+- **Autonomous orchestration**: Single `orchestrate` tool runs a claim→implement→complete loop until all stories pass
+- **Agent status tracking**: Monitor spawned agents by PID, check exit codes, and tail output in real-time
+- **Smart retry**: Automatically suggests or uses a different agent when one fails
+- **Workflow management**: Phases, strategic decisions, and agent assignments
 - **Watch/polling**: Monitor for new messages with cursor-based polling
 - **Auto-archiving**: Archive old messages to keep the chat file manageable
-- **Universal compatibility**: Works with any MCP-supporting tool
+- **Cross-platform**: Works on Windows, Linux, and macOS (uses cross-spawn and platform-safe process management)
+- **Universal compatibility**: Works with any MCP-supporting tool (42 tools across 8 categories)
 - **Simple file-based storage**: No external services required
 
 ## Installation
@@ -27,6 +32,11 @@ An MCP (Model Context Protocol) server that enables multi-agent communication an
 npm install -g nightshift-mcp
 ```
 
+**Updating:**
+```bash
+npm update -g nightshift-mcp
+```
+
 **Or build from source:**
 ```bash
 git clone <repo-url>
@@ -44,11 +54,8 @@ npm link  # makes 'nightshift-mcp' available globally
 {
   "mcpServers": {
     "nightshift": {
-      "command": "node",
-      "args": ["/path/to/nightshift-mcp/dist/index.js"],
-      "env": {
-        "ROBOT_CHAT_PROJECT_PATH": "${PWD}"
-      }
+      "command": "nightshift-mcp",
+      "args": []
     }
   }
 }
@@ -58,11 +65,12 @@ npm link  # makes 'nightshift-mcp' available globally
 
 ```toml
 [mcp_servers.nightshift]
-command = "node"
-args = ["/path/to/nightshift-mcp/dist/index.js"]
-env = { ROBOT_CHAT_PROJECT_PATH = "${PWD}" }
+command = "nightshift-mcp"
+args = []
 ```
 
+The server automatically uses the current working directory for the `.robot-chat/` folder. You can override this with the `ROBOT_CHAT_PROJECT_PATH` environment variable if needed.
+
 ## Usage
 
 For agents to communicate, they must be running in the **same project directory**. The chat file is created at `<project>/.robot-chat/chat.txt` based on where each CLI is started.
@@ -261,7 +269,6 @@ NightShift includes Ralph-compatible PRD and progress management, enabling struc
 ```json
 {
   "project": "MyApp",
-  "branchName": "feature/my-feature",
   "description": "Feature description",
   "userStories": [
     {
@@ -281,6 +288,37 @@ NightShift includes Ralph-compatible PRD and progress management, enabling struc
 }
 ```
 
+### PRD Schema
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `project` | string | no | — | Project name |
+| `description` | string | no | "" | Project description |
+| **`userStories`** | array | **yes** | — | Array of user story objects |
+
+**User Story fields:**
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| **`id`** | string | **yes** | — | Unique ID (e.g., "US-001") |
+| **`title`** | string | **yes** | — | Short title |
+| `description` | string | no | "" | Detailed description |
+| `acceptanceCriteria` | string[] | no | [] | Criteria for completion |
+| `priority` | number | no | 999 | Lower = higher priority |
+| `passes` | boolean | no | false | Whether the story is complete |
+| `notes` | string | no | "" | Implementation notes |
+
+### PRD Validation
+
+NightShift validates your `prd.json` with Zod schemas and provides helpful error messages when common mistakes are detected:
+
+- Using `stories` instead of `userStories` → suggests the correct field name
+- Using `acceptance_criteria` instead of `acceptanceCriteria` → suggests the correct field name
+- Missing required fields (`id`, `title`) → identifies which story has the issue
+- Optional fields default gracefully (`passes` → false, `notes` → "", `acceptanceCriteria` → [])
+
+Use `nightshift_setup(showExamples: true)` for the full schema reference and examples.
+
 2. Agents use these tools to work through stories:
 
 ### PRD Tools
@@ -472,6 +510,50 @@ rollback_savepoint("US-002")
 # → All changes after US-002 discarded
 ```
 
+## Workflow Management
+
+NightShift includes workflow tools for tracking project phases, recording strategic decisions, and managing agent assignments.
+
+### Workflow Tools
+
+#### `init_workflow`
+Initialize a new workflow with a project goal and optional custom phases.
+
+**Parameters:**
+- `projectGoal` (required): High-level goal of the project
+- `phases` (optional): Custom phases (default: research, decisions, planning, build, test, report)
+
+#### `get_workflow_state`
+Get the current workflow state including phase, assignments, and decisions.
+
+#### `advance_phase`
+Advance to the next workflow phase when the current phase's exit criteria are met.
+
+#### `set_phase`
+Manually set the workflow to a specific phase.
+
+**Parameters:**
+- `phase` (required): Target phase (research, decisions, planning, build, test, report, complete)
+
+#### `record_decision`
+Record a strategic decision with rationale for future reference.
+
+**Parameters:**
+- `topic` (required): What the decision is about
+- `options` (required): Options that were considered
+- `chosen` (required): The chosen option
+- `rationale` (required): Why this option was chosen
+- `decidedBy` (required): Agent or person who decided
+
+#### `get_decisions`
+Get all recorded decisions, optionally filtered by topic.
+
+#### `get_active_assignments`
+Get all stories currently being worked on by agents.
+
+#### `clear_assignment`
+Clear a story assignment (for abandonment/failover scenarios).
+
 ## Setup & Debugging
 
 NightShift includes self-service tools for setup and troubleshooting.
@@ -512,14 +594,14 @@ nightshift_debug
 # Returns detailed diagnostic report with suggested fixes
 ```
 
-## Agent Spawning (Autonomous Orchestration)
+## Agent Spawning & Orchestration
 
 One agent can spawn others as subprocesses, enabling fully autonomous multi-agent workflows with minimal user intervention.
 
-### Tools
+### Spawning Tools
 
 #### `list_available_agents`
-Check which agent CLIs (claude, codex, gemini, vibe) are installed.
+Check which agent CLIs (claude, codex, gemini, vibe) are installed and ready to run.
 
 #### `spawn_agent`
 Spawn another agent as a subprocess and wait for completion.
@@ -535,16 +617,14 @@ spawn_agent(agent: "codex", prompt: "Fix the type errors in src/utils.ts")
 ```
 
 #### `spawn_agent_background`
-Spawn an agent in the background (non-blocking).
+Spawn an agent in the background (non-blocking). Returns immediately with PID and output file path.
 
 **Parameters:**
 - `agent` (required): "claude", "codex", "gemini", or "vibe"
 - `prompt` (required): Task/prompt to send
 
-Returns immediately with PID and output file path.
-
 #### `delegate_story`
-Delegate a PRD user story to another agent with full context.
+Delegate a PRD user story to another agent with full context. On failure, returns a `retryHint` suggesting alternative available agents.
 
 **Parameters:**
 - `agent` (required): "claude", "codex", "gemini", or "vibe"
@@ -562,8 +642,51 @@ The spawned agent receives:
 - Recent chat messages for context
 - Instructions to use nightshift tools for coordination
 
+#### `delegate_research`
+Delegate a research or planning task to Gemini. Ideal for read-only tasks like codebase analysis, architecture planning, code review, and documentation.
+
+**Parameters:**
+- `task` (required): The research/planning task description
+- `context` (optional): Additional context to provide
+- `background` (optional): Run in background (default: false)
+
+### Monitoring Tools
+
+#### `get_agent_status`
+Check the status of a spawned background agent by PID.
+
+**Parameters:**
+- `pid` (required): Process ID of the spawned agent
+
+**Returns:**
+- Whether the agent is still running or has exited
+- Exit code (if finished)
+- Last 30 lines of output
+- Story assignment (if delegated via `delegate_story`)
+
+#### `list_running_agents`
+List all agents spawned in the current session with their status.
+
+**Returns:** Array of agents with PID, agent type, running/exited status, elapsed time, and story assignment.
+
+### Orchestration
+
+#### `orchestrate`
+Run an autonomous orchestration loop that claims stories, implements them, and marks them complete until all work is done. This is the highest-level automation tool.
+
+**Parameters:**
+- `agent` (optional): Your agent name (default: "NightShift")
+- `maxIterations` (optional): Maximum stories to process (default: 50)
+- `mode` (optional): "stories", "bugs", or "all" (default: "all")
+
 ### Orchestration Patterns
 
+**Fully autonomous (recommended):**
+```
+orchestrate(agent: "Claude", mode: "all")
+# Runs until all stories and bugs are complete
+```
+
 **Sequential delegation:**
 ```
 delegate_story(agent: "codex")        # Wait for completion
@@ -575,11 +698,14 @@ delegate_story(agent: "gemini")       # Then delegate next
 delegate_story(agent: "codex", storyId: "US-001", background: true)
 delegate_story(agent: "gemini", storyId: "US-002", background: true)
 # Work on US-003 yourself while they run in parallel
+# Monitor with get_agent_status or list_running_agents
 ```
 
-**Ad-hoc task delegation:**
+**Research then implement:**
 ```
-spawn_agent(agent: "claude", prompt: "Review the auth module and suggest improvements")
+delegate_research(task: "Analyze auth patterns and recommend approach")
+# Use findings to inform implementation
+delegate_story(agent: "codex", storyId: "US-001")
 ```
 
 ## NightShift Daemon (Continuous Orchestration)
@@ -604,9 +730,10 @@ The daemon provides hands-off multi-agent orchestration:
 1. **Event-Driven**: Watches `prd.json` and `chat.txt` for changes
 2. **Auto-Spawning**: Spawns agents for orphaned stories (up to concurrency limit)
 3. **Failover Handling**: Automatically claims and reassigns failover requests
-4. **Health Checks**: Periodic reconciliation as a fallback (default: every 2 min)
-5. **Poison Pill Protection**: Quarantines stories that fail repeatedly
-6. **Stuck Detection**: Kills agents that haven't reported activity
+4. **Smart Retry**: Tracks failed agents per story and tries a different agent on retry
+5. **Health Checks**: Periodic reconciliation as a fallback (default: every 2 min)
+6. **Poison Pill Protection**: Quarantines stories that fail repeatedly
+7. **Stuck Detection**: Kills agents that haven't reported activity
 
 ### Options
 
@@ -663,7 +790,9 @@ The daemon provides hands-off multi-agent orchestration:
 4. **Document learnings**: Progress.txt helps future iterations
 5. **Handle failovers**: Check for and claim failovers at the start of each session
 6. **Use delegation**: One orchestrating agent can spawn others for parallel work
-7. **Add `.robot-chat/` to your project's `.gitignore`**: Chat logs are ephemeral and shouldn't be committed
+7. **Monitor background agents**: Use `get_agent_status` and `list_running_agents` to track spawned agents
+8. **Use `orchestrate` for full autonomy**: The `orchestrate` tool handles the entire claim→implement→complete loop
+9. **Add `.robot-chat/` to your project's `.gitignore`**: Chat logs are ephemeral and shouldn't be committed
 
 ## License
 

package/dist/agent-spawner.d.ts

@@ -1,4 +1,43 @@
 export type AgentType = "claude" | "codex" | "gemini" | "vibe";
+export interface TrackedAgent {
+    agent: AgentType;
+    pid: number | undefined;
+    outputFile: string;
+    startTime: number;
+    storyId?: string;
+    prompt: string;
+}
+/**
+ * Update a tracked agent's metadata (e.g., attach a storyId after spawning)
+ */
+export declare function updateTrackedAgent(pid: number, update: {
+    storyId?: string;
+}): void;
+/**
+ * Get the status of a tracked agent by PID
+ */
+export declare function getTrackedAgentStatus(pid: number): {
+    found: boolean;
+    running?: boolean;
+    agent?: AgentType;
+    outputFile?: string;
+    startTime?: number;
+    storyId?: string;
+    exitCode?: number | null;
+    tailOutput?: string;
+};
+/**
+ * List all tracked agents with their current status
+ */
+export declare function listTrackedAgents(): Array<{
+    pid: number | undefined;
+    agent: AgentType;
+    outputFile: string;
+    startTime: number;
+    storyId?: string;
+    running: boolean;
+    elapsedSeconds: number;
+}>;
 export interface SpawnOptions {
     agent: AgentType;
     prompt: string;
@@ -15,13 +54,11 @@ export interface SpawnResult {
 }
 /**
  * Spawn an AI agent as a subprocess
- * For agents requiring PTY, uses script command to allocate one
  */
 export declare function spawnAgent(options: SpawnOptions): Promise<SpawnResult>;
 /**
  * Spawn an agent in the background (non-blocking)
- * Uses safe prompt escaping to prevent command injection
- * Uses PTY allocation via `script` command for agents that require it (like Codex)
+ * Uses a Node.js wrapper script for cross-platform compatibility
  */
 export declare function spawnAgentBackground(options: SpawnOptions): {
     pid: number | undefined;
@@ -33,7 +70,7 @@ export declare function spawnAgentBackground(options: SpawnOptions): {
  */
 export declare function isAgentAvailable(agent: AgentType): Promise<boolean>;
 /**
- * Check if an agent can actually run (verifies PTY requirements are met)
+ * Check if an agent can actually run
  */
 export declare function canAgentRun(agent: AgentType): Promise<{
     available: boolean;
@@ -41,7 +78,7 @@ export declare function canAgentRun(agent: AgentType): Promise<{
     reason?: string;
 }>;
 /**
- * Get list of available agents with their run status
+ * Get list of available agents
  */
 export declare function getAvailableAgents(): Promise<AgentType[]>;
 /**

package/dist/agent-spawner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-spawner.d.ts","sourceRoot":"","sources":["../src/agent-spawner.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAI/D,MAAM,WAAW,YAAY;IAE3B,KAAK,EAAE,SAAS,CAAC;IAEjB,MAAM,EAAE,MAAM,CAAC;IAEf,WAAW,EAAE,MAAM,CAAC;IAEpB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,UAAU,CAAC,EAAE,OAAO,CAAC;CAEtB;AAID,MAAM,WAAW,WAAW;IAE1B,OAAO,EAAE,OAAO,CAAC;IAEjB,MAAM,EAAE,MAAM,CAAC;IAEf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAExB,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,KAAK,CAAC,EAAE,MAAM,CAAC;CAEhB;AAuFD;;;GAGG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAsG5E;AAmJD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,YAAY,GAAG;IAC3D,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAwHA;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAczE;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC;IAC3D,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC,CAyBD;AAED;;GAEG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC,CAW/D;AAED;;GAEG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAC7C,MAAM,CAAC,SAAS,EAAE;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAC5E,CAYA"}
+{"version":3,"file":"agent-spawner.d.ts","sourceRoot":"","sources":["../src/agent-spawner.ts"],"names":[],"mappings":"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"}