@shepai/cli 1.14.1 → 1.15.0

package/README.md

@@ -1,10 +1,10 @@
 <div align="center">
 
-# 🐑 Shep AI
+# Shep AI
 
-### Autonomous AI Native SDLC Platform
+### Multi-Session SDLC Control Center for AI Coding Agents
 
-_Automate the entire development cycle from idea to deploy_
+_Manage Claude Code, Cursor CLI, or any coding agent across the full development lifecycle — from requirements to deploy — with parallel sessions, instant context switching, and human-in-the-loop control_
 
 [![CI](https://github.com/shep-ai/cli/actions/workflows/ci.yml/badge.svg)](https://github.com/shep-ai/cli/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/@shepai/cli.svg?color=cb3837&logo=npm)](https://www.npmjs.com/package/@shepai/cli)
@@ -17,104 +17,210 @@ _Automate the entire development cycle from idea to deploy_
 
 <br />
 
-[Getting Started](#quick-start) •
-[Documentation](#documentation) •
-[Contributing](#contributing) •
-[License](#license)
+[Features](#features) · [Quick Start](#quick-start) · [CLI Reference](#cli) · [Architecture](#architecture) · [Contributing](#contributing)
+
+<br />
+
+<img src="docs/poc/imgs/00-control-center-hero.png" alt="Shep AI Control Center — manage all features across repos from a single canvas" width="100%" />
+
+<br />
 
 </div>
 
 ---
 
-Shep is an intelligent CLI tool that transforms how you build software. Point it at any repository, and it will analyze your codebase, gather requirements through conversational AI, break down features into actionable tasks, generate comprehensive documentation, and execute implementation autonomously.
-
-## Installation
+Running AI agents is easy. **Managing many of them through a full SDLC is the hard part.** Shep gives you a control center that handles the entire lifecycle — requirements gathering, planning, implementation, QA, and deployment — across multiple agent sessions running in parallel. See what each agent is doing, jump into any session's web preview, code editor, or terminal, approve plans when agents need your input, and let them keep working while you move on. Plug in Claude Code, Cursor CLI, Gemini CLI, or any coding agent. Each feature gets its own isolated worktree and dev environment. You manage the lifecycle, agents do the work.
 
 ```bash
-pnpm add -g @shepai/cli
+npm i -g @shepai/cli
+cd your-repo/
+shep feat new "Implement SSO with SAML 2.0"
+# Agent starts working in a dedicated worktree.
+# Open the control center to watch progress, intervene, or switch context.
+shep ui
 ```
 
-Or with npm:
+---
 
-```bash
-npm install -g @shepai/cli
-```
+## Features
 
-## Quick Start
+<table>
+<tr>
+<td width="55%"><img src="docs/poc/imgs/01-features-control-center-overview.png" alt="Feature properties with attachments and metadata" /></td>
+<td width="45%">
 
-```bash
-cd ~/repos/your-project
-shep
-```
+### Feature Properties & Attachments
 
-Or explicitly initialize:
+- **Rich feature detail panel** with name, description, and metadata
+- **File attachments** — requirements PDFs, mockup images, API specs linked directly to features
+- **Team & metadata** tracking for ownership and collaboration
+- **Dependency mapping** between features across repos
+- **Iterative refinement** — update properties as requirements evolve through the lifecycle
 
-```bash
-shep --init
-```
+</td>
+</tr>
 
-This launches a TUI wizard to:
+<tr>
+<td width="55%"><img src="docs/poc/imgs/02-feature-card-action-toolbar.png" alt="Feature card with action toolbar" /></td>
+<td width="45%">
 
-1. Configure Claude Code authentication (setup token or use existing session)
-2. Start repository analysis
-3. Open the web UI at `http://localhost:4050/`
+### Feature Cards with Quick Actions
 
-## How It Works
+- **One-click dev server** launch directly from any card
+- **Action toolbar** — GitHub, web preview, terminal, code editor at your fingertips
+- **Live progress** tracking with percentage and lifecycle stage badge
+- **Unique IDs** for instant cross-referencing across CLI and UI
 
-### Repository Analysis
+</td>
+</tr>
 
-When you run `shep`, it performs comprehensive multi-perspective analysis of your codebase:
+<tr>
+<td width="55%"><img src="docs/poc/imgs/03-requirements-discovery-validation.png" alt="Requirements discovery questionnaire" /></td>
+<td width="45%">
 
-- Architecture patterns and structure
-- Technology stack detection
-- Code conventions and style
-- Dependency mapping
-- Testing patterns
-- Documentation coverage
+### AI-Guided Requirements Discovery
 
-Analysis results are persisted in `~/.shep/repos/<encoded-repo-path>/docs/` for instant access on subsequent runs.
+- **Smart questionnaires** that surface the right questions for your feature
+- **Categorized inputs** — business, technical, and UX problem classification
+- **Priority tiers** (P1–P3) with clear impact descriptions
+- **Domain tagging** to scope the affected areas of your codebase
+- **Human breakpoint** — agent pauses here until you finalize
 
-### Feature Lifecycle
+</td>
+</tr>
 
-Every feature follows the SDLC lifecycle:
+<tr>
+<td width="55%"><img src="docs/poc/imgs/04-technical-implementation-plan-review.png" alt="Technical plan review with architecture decisions" /></td>
+<td width="45%">
 
-```
-Requirements → Plan → Implementation → Test → Deploy → Maintenance
-```
+### Technical Plan Review
 
-#### 1. Requirements Phase
+- **AI-generated implementation plans** with full architecture rationale
+- **Technical decision cards** — see the chosen approach and alternatives side-by-side
+- **Architecture pattern selection** (microservices, monolith, serverless) with trade-off analysis
+- **Approve & continue** or send back for revision — you control the direction
 
-Interactive chat-based gathering powered by repository context. The AI proposes relevant options based on your codebase analysis, ensuring no open questions remain.
+</td>
+</tr>
 
-#### 2. Plan Phase
+<tr>
+<td width="55%"><img src="docs/poc/imgs/05-plan-review-tasks-and-artifacts.png" alt="Task breakdown and generated artifacts" /></td>
+<td width="45%">
 
-Automatic breakdown into:
+### Tasks & Generated Artifacts
 
-- **Tasks** - High-level work items with dependencies
-- **Action Items** - Granular steps within tasks
-- **Artifacts** - Generated documentation (PRDs, RFCs, Design Docs, Tech Plans)
+- **Auto-generated documents** — plan.md, tasks.md, data_model.md created from your approved spec
+- **Task breakdown** with dependency tracking and status badges
+- **Artifact browser** — inspect any generated document directly in the panel
+- **Draft indicator** — nothing ships until you explicitly approve
 
-#### 3. Implementation Phase
+</td>
+</tr>
 
-Autonomous code generation using LangGraph agents, executing tasks according to the dependency graph.
+<tr>
+<td width="55%"><img src="docs/poc/imgs/06-qa-check-review.png" alt="QA checklist with all checks passing" /></td>
+<td width="45%">
 
-#### 4. Test → Deploy → Maintenance
+### Quality Assurance Gate
 
-Continuous lifecycle management with AI assistance at every stage.
+- **Automated QA checklist** — functional, performance, compatibility, accessibility
+- **Performance benchmarks** — API response time p95 thresholds
+- **WCAG 2.5** accessibility compliance verification
+- **One-click Pass QA** when all checks are green
 
-## Spec-Driven Development
+</td>
+</tr>
 
-All contributions follow our spec-driven workflow:
+<tr>
+<td width="55%"><img src="docs/poc/imgs/07-dev-environment-web-preview.png" alt="Integrated web preview in dev environment" /></td>
+<td width="45%">
 
-```
-/shep-kit:new-feature → /shep-kit:research → /shep-kit:plan → implement
+### Integrated Dev Environment — Web Preview
+
+- **Live localhost preview** embedded in the control center
+- **Isolated ports** — each feature runs its own dev server
+- **Server status** indicator with start/stop controls
+- **Open in Browser** for full-screen testing
+- **PR context** — branch, worktree path, and PR link always visible
+
+</td>
+</tr>
+
+<tr>
+<td width="55%"><img src="docs/poc/imgs/08-dev-environment-vscode-tab.png" alt="Embedded VS Code editor in dev environment" /></td>
+<td width="45%">
+
+### Integrated Dev Environment — Code Editor
+
+- **Embedded VS Code** with full editor capabilities
+- **Git worktree isolation** — each feature in its own directory, no branch conflicts
+- **File explorer** with project structure at a glance
+- **PR badge** with commits ahead/behind and changed file count
+- **Zero context-switch** — edit code without leaving the control center
+
+</td>
+</tr>
+
+<tr>
+<td width="55%"><img src="docs/poc/imgs/09-dev-environment-terminal-tab.png" alt="Terminal tab showing running dev server" /></td>
+<td width="45%">
+
+### Integrated Dev Environment — Terminal
+
+- **Full terminal access** inside the feature workspace
+- **Build output, test results, agent logs** in one place
+- **Pre-configured** in the feature's worktree directory
+- **Dev server output** — see Next.js/Vite/Express startup and compile times
+- **Three-tab workflow** — preview, code, and terminal without leaving the UI
+
+</td>
+</tr>
+</table>
+
+---
+
+## Quick Start
+
+```bash
+# Install
+npm i -g @shepai/cli
+
+# Start the background service
+shep start
+#  ➜  Local:   http://localhost:5173/
+#  Shep service is running in background, have fun!
+
+# Navigate to any repo
+cd ~/repos/your-project
+
+# Create your first feature
+shep feat new "Add user authentication with OAuth 2.0"
+
+# Open the control center
+shep ui
 ```
 
-Every feature begins with a specification in `specs/NNN-feature-name/` before any implementation code is written. See [Spec-Driven Workflow](./docs/development/spec-driven-workflow.md) for details.
+## CLI
+
+```
+shep start                            Start background service
+shep feat new <description>           Create a new feature
+shep feat new --interactive           Interactive mode with human checkpoints
+shep feat new --allow-all             Full autonomous mode
+shep feat ls                          List features across repos
+shep feat show <id>                   Show feature details
+shep feat preview <id>                Preview feature dev environment
+shep ui                               Open the web control center
+shep settings show                    Display current configuration
+shep settings agent                   Configure AI coding agent
+shep mem add <text> --global|--repo   Add agent memory
+shep mem ls                           List memories
+shep version                          Version info
+```
 
 ## Architecture
 
-Shep follows **Clean Architecture** principles:
+Clean Architecture with four layers. Dependencies point inward — domain has zero external deps.
 
 ```mermaid
 flowchart TB
@@ -132,15 +238,20 @@ flowchart TB
     style I fill:#ede9fe,stroke:#8b5cf6,color:#4c1d95
 ```
 
-### Data Persistence
+### Feature Lifecycle
+
+Every feature progresses through a structured SDLC pipeline:
 
-Uses **Repository Pattern** with SQLite:
+```
+Requirements → Research → Review PRD → Planning → Review Plan → Implementation → QA → Approval → Live
+     ↑              ↑           ↑            ↑           ↑             ↑          ↑        ↑
+   Agent         Agent       Human        Agent       Human        Agent      Human    Human
+                           breakpoint                breakpoint               check    gate
+```
 
-- Database location: `~/.shep/repos/<encoded-repo-path>/data`
-- Interface-driven design for testability
-- Supports future backend swaps
+Breakpoints are configurable. In `--allow-all` mode, the agent handles everything autonomously.
 
-## Tech Stack
+### Tech Stack
 
 | Component       | Technology                                                                              |
 | --------------- | --------------------------------------------------------------------------------------- |
@@ -157,22 +268,17 @@ Uses **Repository Pattern** with SQLite:
 | Embeddings      | [Transformers.js](https://huggingface.co/docs/transformers.js) (local, multiple models) |
 | Testing         | Vitest (unit/integration) + Playwright (e2e)                                            |
 | Methodology     | TDD (Red-Green-Refactor)                                                                |
-| Security        | Trivy, Gitleaks, Semgrep, Hadolint (CI gates)                                           |
-
-## Security
-
-Automated security scanning runs on every push and PR:
 
-| Scanner      | Purpose                                    |
-| ------------ | ------------------------------------------ |
-| **Trivy**    | Dependency & container vulnerability scans |
-| **Gitleaks** | Secret detection in git history            |
-| **Semgrep**  | SAST for TypeScript/JavaScript             |
-| **Hadolint** | Dockerfile best practices                  |
+### Data Model
 
-Security gates **block releases** on main—all scanners must pass before npm publish and Docker push.
+```
+Repository ──┬── Feature ──┬── Plan ──┬── Task ──── ActionItem
+             │             │          └── Artifact
+             │             └── Requirement ── Research
+             └── Analysis docs (cached)
+```
 
-See [CI/CD Documentation](./docs/development/cicd.md) for details.
+All data lives locally in `~/.shep/`. Per-repo SQLite databases. No cloud dependency.
 
 ## Documentation
 
@@ -191,28 +297,12 @@ See [CI/CD Documentation](./docs/development/cicd.md) for details.
 
 ## Contributing
 
-We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for human contributors and [CONTRIBUTING-AGENTS.md](./CONTRIBUTING-AGENTS.md) for AI agents.
-
-## License
+We welcome contributions from humans and AI agents alike.
 
-MIT License - see [LICENSE](./LICENSE) for details.
+- **Humans**: See [CONTRIBUTING.md](./CONTRIBUTING.md)
+- **AI Agents**: See [CONTRIBUTING-AGENTS.md](./CONTRIBUTING-AGENTS.md)
+- **Spec-driven workflow**: All features start with `/shep-kit:new-feature` — see [Spec-Driven Workflow](./docs/development/spec-driven-workflow.md)
 
----
-
-## Maintaining This Document
-
-**When to update:**
-
-- New major features or commands
-- Architecture changes
-- Tech stack updates
-- New documentation sections
-
-**Style guide:**
-
-- Keep Quick Start minimal (3-5 steps max)
-- Update badges when versions change
-- Ensure all internal links work
-- Test code examples
+## License
 
-**Related docs:** [CONTRIBUTING.md](./CONTRIBUTING.md), [docs/guides/getting-started.md](./docs/guides/getting-started.md)
+MIT — see [LICENSE](./LICENSE).

package/dist/eslint.config.mjs

@@ -41,6 +41,8 @@ export default tseslint.config(
         // Test outputs
         'test-results/**',
         'playwright-report/**',
+        // POC TypeScript files (not part of main tsconfig)
+        'docs/poc/**/*.ts',
         // Config files that don't need linting
         '*.config.js',
         '*.config.mjs',

package/dist/src/application/ports/output/external-issue-fetcher.interface.d.ts

@@ -0,0 +1,69 @@
+/**
+ * External Issue Fetcher Port Interface
+ *
+ * Output port for fetching issues/tickets from external systems (GitHub, Jira).
+ * Returns a normalized ExternalIssue that can be appended to feature context.
+ *
+ * Following Clean Architecture:
+ * - Application layer depends on this interface
+ * - Infrastructure layer provides concrete implementations
+ */
+/**
+ * Normalized issue representation from any external source.
+ */
+export interface ExternalIssue {
+    title: string;
+    description: string;
+    labels: string[];
+    url: string;
+    source: 'github' | 'jira';
+}
+/**
+ * Service interface for fetching issues from external systems.
+ */
+export interface IExternalIssueFetcher {
+    /**
+     * Fetch a GitHub issue by reference.
+     * Supports formats: owner/repo#123 or #123 (uses current repo).
+     *
+     * @param ref - GitHub issue reference (e.g., "owner/repo#42" or "#42")
+     * @returns Normalized external issue
+     * @throws IssueNotFoundError if issue doesn't exist
+     * @throws IssueServiceUnavailableError if gh CLI is not installed
+     */
+    fetchGitHubIssue(ref: string): Promise<ExternalIssue>;
+    /**
+     * Fetch a Jira ticket by key.
+     *
+     * @param key - Jira ticket key (e.g., "PROJ-123")
+     * @returns Normalized external issue
+     * @throws IssueNotFoundError if ticket doesn't exist
+     * @throws IssueAuthenticationError if credentials are invalid
+     */
+    fetchJiraTicket(key: string): Promise<ExternalIssue>;
+}
+/**
+ * Base error for issue fetcher failures.
+ */
+export declare class IssueFetcherError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when the requested issue/ticket is not found.
+ */
+export declare class IssueNotFoundError extends IssueFetcherError {
+    constructor(message: string);
+}
+/**
+ * Thrown when authentication to the external service fails.
+ */
+export declare class IssueAuthenticationError extends IssueFetcherError {
+    constructor(message: string);
+}
+/**
+ * Thrown when the external service is unavailable (e.g., gh CLI not installed).
+ */
+export declare class IssueServiceUnavailableError extends IssueFetcherError {
+    constructor(message: string);
+}
+//# sourceMappingURL=external-issue-fetcher.interface.d.ts.map

package/dist/src/application/ports/output/external-issue-fetcher.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-issue-fetcher.interface.d.ts","sourceRoot":"","sources":["../../../../../src/application/ports/output/external-issue-fetcher.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,QAAQ,GAAG,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;OAQG;IACH,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAEtD;;;;;;;OAOG;IACH,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CACtD;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,iBAAiB;gBAC3C,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,wBAAyB,SAAQ,iBAAiB;gBACjD,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,4BAA6B,SAAQ,iBAAiB;gBACrD,OAAO,EAAE,MAAM;CAI5B"}

package/dist/src/application/ports/output/external-issue-fetcher.interface.js

@@ -0,0 +1,46 @@
+/**
+ * External Issue Fetcher Port Interface
+ *
+ * Output port for fetching issues/tickets from external systems (GitHub, Jira).
+ * Returns a normalized ExternalIssue that can be appended to feature context.
+ *
+ * Following Clean Architecture:
+ * - Application layer depends on this interface
+ * - Infrastructure layer provides concrete implementations
+ */
+/**
+ * Base error for issue fetcher failures.
+ */
+export class IssueFetcherError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'IssueFetcherError';
+    }
+}
+/**
+ * Thrown when the requested issue/ticket is not found.
+ */
+export class IssueNotFoundError extends IssueFetcherError {
+    constructor(message) {
+        super(message);
+        this.name = 'IssueNotFoundError';
+    }
+}
+/**
+ * Thrown when authentication to the external service fails.
+ */
+export class IssueAuthenticationError extends IssueFetcherError {
+    constructor(message) {
+        super(message);
+        this.name = 'IssueAuthenticationError';
+    }
+}
+/**
+ * Thrown when the external service is unavailable (e.g., gh CLI not installed).
+ */
+export class IssueServiceUnavailableError extends IssueFetcherError {
+    constructor(message) {
+        super(message);
+        this.name = 'IssueServiceUnavailableError';
+    }
+}

package/dist/src/application/ports/output/feature-agent-process.interface.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Feature Agent Process Service Interface
+ *
+ * Output port for managing feature agent background processes.
+ * Implementations handle forking worker processes, checking liveness,
+ * and marking crashed processes.
+ *
+ * Following Clean Architecture:
+ * - Application layer depends on this interface
+ * - Infrastructure layer provides concrete implementation
+ */
+/**
+ * Service interface for feature agent background process management.
+ */
+export interface IFeatureAgentProcessService {
+    /**
+     * Spawn a background worker process for a feature agent run.
+     *
+     * @param featureId - The feature ID to process
+     * @param runId - The agent run ID for tracking
+     * @param repoPath - Repository path for context
+     * @param specDir - Spec directory path
+     * @returns The PID of the spawned process
+     */
+    spawn(featureId: string, runId: string, repoPath: string, specDir: string, worktreePath?: string, options?: {
+        approvalMode?: string;
+        resume?: boolean;
+    }): number;
+    /**
+     * Check if a process is still alive.
+     *
+     * @param pid - The process ID to check
+     * @returns True if the process is running
+     */
+    isAlive(pid: number): boolean;
+    /**
+     * Check if the process for an agent run is alive.
+     * If the process is dead, mark the run as interrupted.
+     *
+     * @param runId - The agent run ID to check
+     */
+    checkAndMarkCrashed(runId: string): Promise<void>;
+}
+//# sourceMappingURL=feature-agent-process.interface.d.ts.map

package/dist/src/application/ports/output/feature-agent-process.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-agent-process.interface.d.ts","sourceRoot":"","sources":["../../../../../src/application/ports/output/feature-agent-process.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;;;;;;;OAQG;IACH,KAAK,CACH,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,YAAY,CAAC,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GACpD,MAAM,CAAC;IAEV;;;;;OAKG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAE9B;;;;;OAKG;IACH,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD"}

package/dist/src/application/ports/output/feature-agent-process.interface.js

@@ -0,0 +1,12 @@
+/**
+ * Feature Agent Process Service Interface
+ *
+ * Output port for managing feature agent background processes.
+ * Implementations handle forking worker processes, checking liveness,
+ * and marking crashed processes.
+ *
+ * Following Clean Architecture:
+ * - Application layer depends on this interface
+ * - Infrastructure layer provides concrete implementation
+ */
+export {};

package/dist/src/application/ports/output/feature-repository.interface.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Feature Repository Interface
+ *
+ * Output port for Feature persistence operations.
+ * Implementations handle database-specific logic (SQLite, etc.).
+ *
+ * Following Clean Architecture:
+ * - Domain and Application layers depend on this interface
+ * - Infrastructure layer provides concrete implementations
+ */
+import type { Feature, SdlcLifecycle } from '../../../domain/generated/output.js';
+/**
+ * Filters for listing features.
+ */
+export interface FeatureListFilters {
+    repositoryPath?: string;
+    lifecycle?: SdlcLifecycle;
+}
+/**
+ * Repository interface for Feature entity persistence.
+ *
+ * Implementations must:
+ * - Handle database connection management
+ * - Provide thread-safe operations
+ * - Support query by slug + repositoryPath for uniqueness
+ */
+export interface IFeatureRepository {
+    /**
+     * Create a new feature record.
+     *
+     * @param feature - The feature to persist
+     */
+    create(feature: Feature): Promise<void>;
+    /**
+     * Find a feature by its unique ID.
+     *
+     * @param id - The feature ID
+     * @returns The feature or null if not found
+     */
+    findById(id: string): Promise<Feature | null>;
+    /**
+     * Find a feature by an ID prefix (e.g. first 8 chars from `feat ls`).
+     *
+     * @param prefix - A prefix of the feature UUID
+     * @returns The feature if exactly one match, null if none, throws if ambiguous
+     */
+    findByIdPrefix(prefix: string): Promise<Feature | null>;
+    /**
+     * Find a feature by its slug within a repository.
+     *
+     * @param slug - The URL-friendly feature identifier
+     * @param repositoryPath - The repository path to scope the search
+     * @returns The feature or null if not found
+     */
+    findBySlug(slug: string, repositoryPath: string): Promise<Feature | null>;
+    /**
+     * List features with optional filters.
+     *
+     * @param filters - Optional filters for repositoryPath and lifecycle
+     * @returns Array of matching features
+     */
+    list(filters?: FeatureListFilters): Promise<Feature[]>;
+    /**
+     * Update an existing feature.
+     *
+     * @param feature - The feature with updated fields
+     */
+    update(feature: Feature): Promise<void>;
+    /**
+     * Delete a feature by ID.
+     *
+     * @param id - The feature ID to delete
+     */
+    delete(id: string): Promise<void>;
+}
+//# sourceMappingURL=feature-repository.interface.d.ts.map

package/dist/src/application/ports/output/feature-repository.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-repository.interface.d.ts","sourceRoot":"","sources":["../../../../../src/application/ports/output/feature-repository.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AAElF;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,aAAa,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IAE9C;;;;;OAKG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IAExD;;;;;;OAMG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IAE1E;;;;;OAKG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAEvD;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExC;;;;OAIG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnC"}

package/dist/src/application/ports/output/feature-repository.interface.js

@@ -0,0 +1,11 @@
+/**
+ * Feature Repository Interface
+ *
+ * Output port for Feature persistence operations.
+ * Implementations handle database-specific logic (SQLite, etc.).
+ *
+ * Following Clean Architecture:
+ * - Domain and Application layers depend on this interface
+ * - Infrastructure layer provides concrete implementations
+ */
+export {};

package/dist/src/application/ports/output/index.d.ts

@@ -13,4 +13,7 @@ export type { IAgentExecutorFactory } from './agent-executor-factory.interface.j
 export type { IAgentRunner, AgentRunOptions } from './agent-runner.interface.js';
 export type { IAgentRegistry, AgentDefinitionWithFactory } from './agent-registry.interface.js';
 export type { IAgentRunRepository } from './agent-run-repository.interface.js';
+export type { IWorktreeService, WorktreeInfo } from './worktree-service.interface.js';
+export { WorktreeError, WorktreeErrorCode } from './worktree-service.interface.js';
+export type { IFeatureAgentProcessService } from './feature-agent-process.interface.js';
 //# sourceMappingURL=index.d.ts.map