ralphctl 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,94 @@
+# Changelog
+
+All notable changes to RalphCTL will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-03-07
+
+### Added
+
+- **npm publishing** — `ralphctl` is now available via `npm install -g ralphctl`
+- Release pipeline publishes to npm and creates GitHub Releases with changelog-based notes
+
+### Changed
+
+- Streamlined README for end-user onboarding with `npm install -g` as primary install method
+- Added release process documentation to CONTRIBUTING.md
+- Version bumped to 0.1.0 for first public npm release
+
+## [0.0.3] - 2026-03-06
+
+### Changed
+
+- Normalized git author identity across commit history
+- Updated package metadata for open-source release (description, homepage, private flag)
+- Moved `tsx` from devDependencies to dependencies (runtime requirement for `bin/ralphctl`)
+- Fixed stale path references in SECURITY.md, CONTRIBUTING.md, and agent memory files
+- Fixed changelog compare link in release workflow to include `v` prefix
+- Corrected documentation table descriptions in README.md
+- Cleaned up stale `dist/` build artifacts
+- Edited documentation for public release
+
+## [0.0.2] - 2026-03-03
+
+### Added
+
+- **Doctor command** — `ralphctl doctor` checks Node.js version, git, AI provider binary, data directory, project repos, and current sprint health
+- **Shell tab-completion** — `ralphctl completion install` for bash, zsh, and fish via tabtab
+- **Branch management** — `sprint start` prompts for branch strategy (keep current, auto, custom); `--branch` and `--branch-name` flags; pre-flight verification; `sprint close --create-pr` creates PRs
+- **Provider abstraction** — `config set provider claude|copilot` with adapter layer; experimental Copilot CLI support with headless execution and session ID capture
+- **Draft re-plan** — running `sprint plan` on a draft with existing tasks passes all tickets + tasks as AI context for atomic replacement
+- **Check script model** — single idempotent `checkScript` per repo replaces old `setupScript`/`verifyScript`; runs at sprint start and as a post-task gate
+- **Lifecycle hooks** — `runLifecycleHook()` abstraction in `src/ai/lifecycle.ts` with `RALPHCTL_LIFECYCLE_EVENT` env var
+- **Ecosystem detection** — `EcosystemDetector[]` registry (node, python, go, rust, gradle, maven, makefile) for check script suggestions during project setup
+- **Sprint health** — duplicate task order and pending requirements diagnostics; branch consistency checks across repos
+- **Interactive mode** — Escape key navigation, styled section titles, flat workflow section, provider config in REPL, refined/planned counts in status header, guards for unrefined/unplanned tickets
+- **Inline multiline editor** — replaced with `@inquirer/editor` and configurable editor settings via `config set editor`
+- **CI/CD** — GitHub Actions pipeline with lint, typecheck, test, format check; Dependabot; automated GitHub Release pipeline
+- **Schema sync tests** — JSON schema ↔ Zod schema validation
+
+### Changed
+
+- Renamed `claude` module to `ai` for provider-agnostic naming
+- Replaced tsup build with bash wrapper approach for CLI outside repo root
+- Default data directory changed to `~/.ralphctl` (was `ralphctl-data/`)
+- Separated repo root from data directory with smart `RALPHCTL_ROOT` handling
+- Removed `externalId` field and `--id`/`--editor` CLI flags from ticket command
+- Documentation restructured — moved to `.claude/docs/`, slimmed CLAUDE.md from 613 to 160 lines with skill-based reference material
+- Replaced raw color functions with theme helpers across all commands
+- Improved card rendering and terminal width awareness
+
+### Fixed
+
+- Sanitize session IDs and harden file operations against path traversal
+- Fixed pre-flight execution checks for security and correctness
+- Preserve error cause in re-thrown errors
+- Thread provider through `checkTaskPermissions()`
+- Branch management error handling and retry logic
+- Interactive mode duplicate quote, closed sprint status header, and dashboard duplication
+- ANSI code handling in CLI test field extraction
+- Removed redundant file reads in interactive menu context loading
+
+### Dependencies
+
+- Bumped `zod` from 3.x to 4.x
+- Bumped `@inquirer/prompts` from 7.x to 8.x
+- Bumped `@types/node`, `globals`, `ora`, `typescript-eslint`, and other dev dependencies
+
+## [0.0.1] - 2026-02-15
+
+### Added
+
+- **Project management** — register multi-repo projects with named paths
+- **Sprint lifecycle** — create, activate, close sprints with state machine enforcement (draft -> active -> closed)
+- **Ticket tracking** — add work items linked to projects, with optional external IDs
+- **Two-phase planning** — refine requirements (WHAT) then generate tasks (HOW) with human approval gates
+- **Task dependencies** — `blockedBy` references with topological sort and cycle detection
+- **Task execution** — headless, watch, session, and interactive modes via Claude CLI
+- **Parallel execution** — one task per repo concurrently, with rate limit backoff and session resume
+- **Interactive menu mode** — context-aware REPL with persistent status header and Quick Start wizard
+- **Sprint health checks** — diagnose blockers, stale tasks, and missing dependencies
+- **Requirements export** — markdown export of refined requirements
+- **Progress logging** — append-only timestamped progress log per sprint
+- **Ralph Wiggum personality** — themed UI with donut spinners, random quotes, and gradient banner

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lukas Grigis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,189 @@
+[![npm version](https://img.shields.io/npm/v/ralphctl?style=flat&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/ralphctl)
+[![CI](https://github.com/lukas-grigis/ralphctl/actions/workflows/ci.yml/badge.svg)](https://github.com/lukas-grigis/ralphctl/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat&logo=opensourceinitiative&logoColor=white)](./LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178c6?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/node-%E2%89%A5_24-5fa04e?style=flat&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat&logo=git&logoColor=white)](./CONTRIBUTING.md)
+
+```
+  🍩 ██████╗  █████╗ ██╗     ██████╗ ██╗  ██╗ ██████╗████████╗██╗     🍩
+     ██╔══██╗██╔══██╗██║     ██╔══██╗██║  ██║██╔════╝╚══██╔══╝██║
+     ██████╔╝███████║██║     ██████╔╝███████║██║        ██║   ██║
+     ██╔══██╗██╔══██║██║     ██╔═══╝ ██╔══██║██║        ██║   ██║
+     ██║  ██║██║  ██║███████╗██║     ██║  ██║╚██████╗   ██║   ███████╗
+     ╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝╚═╝     ╚═╝  ╚═╝ ╚═════╝   ╚═╝   ╚══════╝
+```
+
+**Sprint and task management CLI for AI-assisted coding with Claude Code or GitHub Copilot.**
+
+> _"I'm helping!"_ — Ralph Wiggum
+
+> [!NOTE]
+> **Early access.** RalphCTL is under active development. Things work, but expect rough edges and breaking changes before 1.0. Read the [blog post](https://lukasgrigis.dev/blog/building-ralphctl) for the backstory.
+
+You write tickets, your AI buddy (Claude or Copilot) refines the requirements, then breaks them into tasks and executes them. RalphCTL keeps track of the state so nothing gets lost between sessions. Ralph Wiggum personality included because why not.
+
+---
+
+## Install
+
+```bash
+npm install -g ralphctl
+```
+
+This installs the `ralphctl` command globally.
+
+### Prerequisites
+
+- [Node.js](https://nodejs.org/) **>= 24.0.0**
+- [Git](https://git-scm.com/)
+- Either [Claude CLI](https://docs.anthropic.com/en/docs/claude-code) or [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli) installed and authenticated
+
+### 2-Minute Quick Start
+
+```bash
+# 1. Register a project (points to your repo)
+ralphctl project add
+
+# 2. Create a sprint
+ralphctl sprint create --name "my-first-sprint"
+
+# 3. Add a ticket
+ralphctl ticket add --project my-app --title "Add user authentication"
+
+# 4. Let AI refine requirements, plan tasks, and execute
+ralphctl sprint refine
+ralphctl sprint plan
+ralphctl sprint start
+```
+
+Or just run `ralphctl` with no arguments for an interactive menu that walks you through everything.
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [CLI Overview](#cli-overview)
+- [AI Provider Configuration](#ai-provider-configuration)
+- [Documentation](#documentation)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Features
+
+- **Two-phase planning** — clarify requirements first (what), then generate tasks (how), with a human approval gate between them
+- **Multi-repo sprints** — a single sprint can track tickets across multiple repositories
+- **Task dependencies** — `blockedBy` references with topological sort; tasks run in the right order
+- **Interactive or headless** — pair with Claude in a session, or let it run unattended
+- **Sprint lifecycle** — state machine (draft -> active -> closed) with file locking for concurrent safety
+- **Parallel execution** — one task per repo at a time, with automatic rate limit backoff and session resume
+- **Menu mode** — run `ralphctl` with no arguments for an interactive menu
+
+---
+
+## CLI Overview
+
+| Command                        | Description                             |
+| ------------------------------ | --------------------------------------- |
+| `ralphctl`                     | Interactive menu mode                   |
+| `ralphctl doctor`              | Check environment health and setup      |
+| `ralphctl config show`         | Show current configuration              |
+| `ralphctl config set`          | Set configuration values                |
+| `ralphctl project add`         | Register a project and its repos        |
+| `ralphctl sprint create`       | Create a new sprint                     |
+| `ralphctl sprint list`         | List all sprints                        |
+| `ralphctl sprint show`         | Show current sprint details             |
+| `ralphctl sprint switch`       | Quick sprint switcher                   |
+| `ralphctl ticket add`          | Add a work item to a sprint             |
+| `ralphctl sprint refine`       | Refine requirements with AI             |
+| `ralphctl sprint plan`         | Generate tasks from requirements        |
+| `ralphctl sprint ideate`       | Quick single-session refine + plan      |
+| `ralphctl sprint requirements` | Export refined requirements to markdown |
+| `ralphctl sprint start`        | Execute tasks with AI                   |
+| `ralphctl sprint health`       | Diagnose blockers and stale tasks       |
+| `ralphctl sprint close`        | Close an active sprint                  |
+| `ralphctl sprint delete`       | Delete a sprint permanently             |
+| `ralphctl task list`           | List tasks in the current sprint        |
+| `ralphctl task next`           | Show the next unblocked task            |
+| `ralphctl dashboard`           | Sprint overview with progress bar       |
+| `ralphctl completion install`  | Enable shell tab-completion             |
+
+Run `ralphctl <command> --help` for details on any command.
+
+---
+
+## AI Provider Configuration
+
+RalphCTL supports **Claude Code** and **GitHub Copilot** as AI backends. Both use the same prompt templates and workflow.
+
+```bash
+ralphctl config set provider claude      # Use Claude Code
+ralphctl config set provider copilot     # Use GitHub Copilot
+```
+
+Auto-prompts on first AI command if not set. Both CLIs must be in your PATH and authenticated.
+
+---
+
+## Documentation
+
+| Document                                                    | Description                                    |
+| ----------------------------------------------------------- | ---------------------------------------------- |
+| [REQUIREMENTS.md](./.claude/docs/REQUIREMENTS.md)           | Acceptance criteria and feature requirements   |
+| [ARCHITECTURE.md](./.claude/docs/ARCHITECTURE.md)           | Data models, file storage, and error reference |
+| [CLAUDE.md](./CLAUDE.md)                                    | Developer guide and Claude Code project config |
+| [CONTRIBUTING.md](./CONTRIBUTING.md)                        | How to contribute                              |
+| [CHANGELOG.md](./CHANGELOG.md)                              | Version history                                |
+| [Blog post](https://lukasgrigis.dev/blog/building-ralphctl) | Background and motivation                      |
+
+---
+
+## Data Directory
+
+RalphCTL stores all data in `~/.ralphctl/` by default. Override with `RALPHCTL_ROOT`:
+
+```bash
+export RALPHCTL_ROOT="/path/to/custom/data-dir"
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/lukas-grigis/ralphctl.git
+cd ralphctl
+pnpm install
+pnpm dev --help          # Run CLI in dev mode
+pnpm build               # Type check
+pnpm test                # Run tests
+pnpm lint                # Lint
+```
+
+No compilation step — the CLI runs TypeScript source directly via [tsx](https://tsx.is/).
+
+---
+
+## Contributing
+
+Contributions are welcome! Please **open an issue first** to discuss what you'd like to change.
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full guide — dev setup, code style, PR process, and releasing.
+
+This project follows the [Contributor Covenant](./CODE_OF_CONDUCT.md) code of conduct.
+
+---
+
+## Security
+
+To report a vulnerability, use [GitHub's private reporting](https://github.com/lukas-grigis/ralphctl/security/advisories/new). See [SECURITY.md](./SECURITY.md) for details.
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE) for details.

package/bin/ralphctl

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Resolve symlinks so this works via npm link / pnpm link --global
+SOURCE="${BASH_SOURCE[0]}"
+while [ -L "$SOURCE" ]; do
+  DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+  SOURCE="$(readlink "$SOURCE")"
+  [[ $SOURCE != /* ]] && SOURCE="$DIR/$SOURCE"
+done
+SCRIPT_DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+REPO_DIR="$SCRIPT_DIR/.."
+
+export TSX_TSCONFIG_PATH="$REPO_DIR/tsconfig.json"
+exec node --import tsx "$REPO_DIR/src/cli.ts" "$@"

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "ralphctl",
+  "version": "0.1.0",
+  "description": "Sprint and task management CLI for AI-assisted coding",
+  "homepage": "https://github.com/lukas-grigis/ralphctl",
+  "type": "module",
+  "license": "MIT",
+  "author": "Lukas Grigis",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lukas-grigis/ralphctl.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lukas-grigis/ralphctl/issues"
+  },
+  "keywords": [
+    "cli",
+    "claude",
+    "ai",
+    "sprint",
+    "task-management",
+    "planning",
+    "anthropic",
+    "developer-tools"
+  ],
+  "bin": {
+    "ralphctl": "./bin/ralphctl"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "!src/**/*.test.ts",
+    "!src/test-utils/",
+    "!src/integration/",
+    "schemas/",
+    "tsconfig.json",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc --noEmit",
+    "dev": "tsx src/cli.ts",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "prepare": "husky"
+  },
+  "packageManager": "pnpm@10.29.3",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.3.0",
+    "colorette": "^2.0.20",
+    "commander": "^14.0.3",
+    "gradient-string": "^3.0.0",
+    "ora": "^9.3.0",
+    "tabtab": "^3.0.2",
+    "tsx": "^4.21.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.3.3",
+    "@types/tabtab": "^3.0.4",
+    "eslint": "^10.0.2",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.4.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.3.1",
+    "prettier": "^3.8.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.56.1",
+    "vitest": "^4.0.18"
+  },
+  "lint-staged": {
+    "*.ts": [
+      "eslint --cache --fix",
+      "prettier --write"
+    ],
+    "*.{md,json,yml,yaml}": "prettier --write"
+  }
+}

package/schemas/config.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "config.schema.json",
+  "title": "Config",
+  "description": "RalphCTL configuration",
+  "type": "object",
+  "properties": {
+    "currentSprint": {
+      "type": ["string", "null"],
+      "default": null,
+      "description": "Current sprint ID (which sprint CLI commands target)"
+    },
+    "aiProvider": {
+      "type": ["string", "null"],
+      "enum": ["claude", "copilot", null],
+      "default": null,
+      "description": "AI provider to use for code generation (claude or copilot)"
+    }
+  }
+}

package/schemas/ideate-output.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Ideate Output Schema",
+  "description": "Combined requirements and tasks from sprint ideate command",
+  "type": "object",
+  "required": ["requirements", "tasks"],
+  "properties": {
+    "requirements": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Refined requirements in markdown format"
+    },
+    "tasks": {
+      "type": "array",
+      "description": "Array of implementation tasks",
+      "items": {
+        "$ref": "task-import.schema.json#/definitions/ImportTask"
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/projects.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "projects.schema.json",
+  "title": "Projects",
+  "description": "Array of project definitions",
+  "type": "array",
+  "items": {
+    "type": "object",
+    "required": ["name", "displayName", "repositories"],
+    "properties": {
+      "name": {
+        "type": "string",
+        "pattern": "^[a-z0-9-]+$",
+        "minLength": 1,
+        "description": "Project slug (lowercase, numbers, hyphens only)"
+      },
+      "displayName": {
+        "type": "string",
+        "minLength": 1,
+        "description": "Human-readable project name"
+      },
+      "repositories": {
+        "type": "array",
+        "minItems": 1,
+        "description": "Array of repositories for this project",
+        "items": {
+          "type": "object",
+          "required": ["name", "path"],
+          "properties": {
+            "name": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Repository name (auto-derived from path basename)"
+            },
+            "path": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Absolute path to the repository"
+            },
+            "checkScript": {
+              "type": "string",
+              "description": "Idempotent check command that bootstraps and verifies the environment (e.g., pnpm install && pnpm typecheck && pnpm lint && pnpm test)"
+            }
+          }
+        }
+      },
+      "description": {
+        "type": "string",
+        "description": "Optional project description"
+      }
+    }
+  }
+}

package/schemas/requirements-output.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "requirements-output.schema.json",
+  "title": "Requirements Output",
+  "description": "Schema for refined requirements output from ralphctl sprint refine",
+  "type": "array",
+  "items": {
+    "type": "object",
+    "required": ["ref", "requirements"],
+    "additionalProperties": false,
+    "properties": {
+      "ref": {
+        "type": "string",
+        "minLength": 1,
+        "description": "Reference to the ticket - either internal ID, external ID, or exact title"
+      },
+      "requirements": {
+        "type": "string",
+        "minLength": 1,
+        "description": "Refined requirements in markdown format - should include problem statement, requirements, acceptance criteria, scope, and constraints"
+      }
+    }
+  }
+}

package/schemas/sprint.schema.json

@@ -0,0 +1,109 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "sprint.schema.json",
+  "title": "Sprint",
+  "description": "Sprint metadata and tickets",
+  "type": "object",
+  "required": ["id", "name", "status", "createdAt"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^\\d{8}-\\d{6}-[a-z0-9-]+$",
+      "description": "Sprint ID in format YYYYMMDD-HHmmss-<slug> (lexicographically sortable)"
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable sprint name"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["draft", "active", "closed"],
+      "default": "draft",
+      "description": "Sprint status (one-way: draft → active → closed)"
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when sprint was created"
+    },
+    "activatedAt": {
+      "type": ["string", "null"],
+      "format": "date-time",
+      "default": null,
+      "description": "ISO 8601 timestamp when sprint was activated"
+    },
+    "closedAt": {
+      "type": ["string", "null"],
+      "format": "date-time",
+      "default": null,
+      "description": "ISO 8601 timestamp when sprint was closed"
+    },
+    "checkRanAt": {
+      "type": "object",
+      "default": {},
+      "description": "Map of projectPath → ISO 8601 timestamp recording when check script last ran (per sprint lifecycle)",
+      "additionalProperties": {
+        "type": "string",
+        "format": "date-time"
+      }
+    },
+    "branch": {
+      "type": ["string", "null"],
+      "default": null,
+      "description": "Branch name used for sprint execution. When set, all repos checkout this branch before task execution."
+    },
+    "tickets": {
+      "type": "array",
+      "default": [],
+      "description": "Tickets to be planned into tasks",
+      "items": {
+        "type": "object",
+        "required": ["id", "title", "projectName"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Internal ticket ID (uuid8, auto-generated)"
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Short summary of the work"
+          },
+          "description": {
+            "type": "string",
+            "description": "Detailed description of requirements, acceptance criteria, context"
+          },
+          "link": {
+            "type": "string",
+            "format": "uri",
+            "description": "URL to external issue tracker"
+          },
+          "projectName": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Reference to project name (from projects.json)"
+          },
+          "requirementStatus": {
+            "type": "string",
+            "enum": ["pending", "approved"],
+            "default": "pending",
+            "description": "Status of requirement refinement"
+          },
+          "affectedRepositories": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Repository paths selected during planning"
+          },
+          "requirements": {
+            "type": "string",
+            "description": "Refined requirements (set during sprint refine)"
+          }
+        }
+      }
+    }
+  }
+}