diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 551fce13..16969eea 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -192,6 +192,7 @@ All new or changed behavior must be covered by tests: - **Failure modes**: Error handling and edge cases - **Location**: Prefer tests near the code via `#[cfg(test)]` - **Integration tests**: Use `crates/cueloop/tests/` for cross-module behavior +- **Disposable-repo fixtures**: Some suites assume `main` as the default branch name and exercise `cueloop doctor` against schema-merged defaults (including the built-in `pi` runner for cached non-interactive init fixtures). If only a handful of tests fail with `origin/main` or a missing `pi` binary, see [Environment-dependent integration tests](docs/troubleshooting.md#environment-dependent-integration-tests). - **Agent CI classifier**: If you change `scripts/agent-ci-surface.sh` or path allowlists in `scripts/lib/release_policy.sh`, extend `crates/cueloop/tests/agent_ci_surface_contract_test.rs` so representative `noop` / `ci-docs` / `ci-fast` / `ci` / `macos-ci` routing stays pinned (see `docs/guides/ci-strategy.md`). Example: diff --git a/README.md b/README.md index a34f7fca..3dfa7bf1 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ CueLoop is a Rust CLI and macOS app for queue-driven, auditable AI coding agent [![crates.io](https://img.shields.io/crates/v/cueloop.svg)](https://crates.io/crates/cueloop) [![docs.rs](https://img.shields.io/docsrs/cueloop)](https://docs.rs/cueloop) -[![GitHub release v0.6.0](https://img.shields.io/badge/release-v0.6.0-blue)](https://github.com/fitchmultz/cueloop/releases/tag/v0.6.0) +[![GitHub release v0.7.2](https://img.shields.io/badge/release-v0.7.2-blue)](https://github.com/fitchmultz/cueloop/releases/tag/v0.7.2) ![CueLoop three-phase agent workflow](docs/assets/images/2026-02-07-workflow-3phase.png) @@ -187,19 +187,14 @@ make release-gate ## Documentation -Start with: - -- [Documentation index](docs/index.md) -- [Evaluator path](docs/guides/evaluator-path.md) -- [Quick start](docs/quick-start.md) -- [Local smoke test](docs/guides/local-smoke-test.md) -- [CLI reference](docs/cli.md) -- [Configuration](docs/configuration.md) -- [Architecture overview](docs/architecture.md) -- [Troubleshooting](docs/troubleshooting.md) -- [Versioning policy](docs/versioning-policy.md) -- [Contributing](CONTRIBUTING.md) -- [Changelog](CHANGELOG.md) +Start at [docs/index.md](docs/index.md) for the full map. Common entry points: + +- [Evaluator path](docs/guides/evaluator-path.md) — fastest review path +- [Quick start](docs/quick-start.md) — install and first run +- [Feature guides](docs/features/README.md) — queue, runners, phases, plugins +- [CLI reference](docs/cli.md) and [Configuration](docs/configuration.md) +- [Architecture](docs/architecture.md) and [Troubleshooting](docs/troubleshooting.md) +- [Contributing](CONTRIBUTING.md) and [Changelog](CHANGELOG.md) ## Versioning and license diff --git a/docs/archive/README.md b/docs/archive/README.md new file mode 100644 index 00000000..796907fc --- /dev/null +++ b/docs/archive/README.md @@ -0,0 +1,18 @@ +# Documentation archive + +Status: Archived +Owner: Maintainers +Source of truth: index for historical docs only +Parent: [Documentation index](../index.md) + +These files are kept for context and audit trails. They are not maintained as primary user documentation. For current guidance, start at [docs/index.md](../index.md). + +## Contents + +| Document | Why it is here | +| --- | --- | +| [Stack audit (2026-03)](../guides/stack-audit-2026-03.md) | Superseded by [Stack audit (2026-04)](../guides/stack-audit-2026-04.md) | +| [Codebase audit (2026-03-31)](audits/codebase-audit-2026-03-31.md) | Point-in-time cleanup inventory; follow-ups captured in [roadmap](../roadmap.md) | +| [CueLoopMac settings investigation (2026-03-13)](audits/2026-03-13-cueloopmac-settings-window-investigation.md) | Resolved UI investigation notes | + +When an archived doc disagrees with CLI behavior, trust [CLI reference](../cli.md), [configuration](../configuration.md), and the generated [schemas](../../schemas/). diff --git a/docs/audits/2026-03-13-cueloopmac-settings-window-investigation.md b/docs/archive/audits/2026-03-13-cueloopmac-settings-window-investigation.md similarity index 99% rename from docs/audits/2026-03-13-cueloopmac-settings-window-investigation.md rename to docs/archive/audits/2026-03-13-cueloopmac-settings-window-investigation.md index f8685d1c..e10f8243 100644 --- a/docs/audits/2026-03-13-cueloopmac-settings-window-investigation.md +++ b/docs/archive/audits/2026-03-13-cueloopmac-settings-window-investigation.md @@ -2,7 +2,7 @@ Status: Archived Owner: Maintainers Source of truth: historical snapshot; current guidance lives in linked active docs -Parent: [CueLoop Documentation](../index.md) +Parent: [Documentation archive](../README.md) Date: 2026-03-13 diff --git a/docs/audits/codebase-audit-2026-03-31.md b/docs/archive/audits/codebase-audit-2026-03-31.md similarity index 99% rename from docs/audits/codebase-audit-2026-03-31.md rename to docs/archive/audits/codebase-audit-2026-03-31.md index 51b709f4..c136d369 100644 --- a/docs/audits/codebase-audit-2026-03-31.md +++ b/docs/archive/audits/codebase-audit-2026-03-31.md @@ -2,14 +2,13 @@ Status: Archived Owner: Maintainers Source of truth: historical snapshot; current guidance lives in linked active docs -Parent: [CueLoop Documentation](../index.md) +Parent: [Documentation archive](../README.md) **Date:** 2026-03-31 **Scope:** Full codebase (`crates/cueloop/src`, `crates/cueloop/tests`, `scripts/`, `Makefile`) **Auditor:** AI Agent (comprehensive-codebase-audit skill) ---- ## Executive Summary @@ -36,7 +35,6 @@ Parent: [CueLoop Documentation](../index.md) **Error Handling:** Two-tier `anyhow`/`thiserror` approach is consistently applied. Production code uses `?` operator almost universally. `unwrap()` is confined to test code and `LazyLock` static initialization (acceptable). ---- ## Metrics Dashboard @@ -63,7 +61,6 @@ Parent: [CueLoop Documentation](../index.md) | `todo!()` macros | 0 | | `unreachable!()` in production | 1 | ---- ## Full Findings @@ -98,7 +95,6 @@ Parent: [CueLoop Documentation](../index.md) ✅ **[Module Documentation]** 100% coverage — all 826 source files have `//!` purpose/responsibilities/scope/usage/invariants headers. ---- ### SECURITY @@ -129,7 +125,6 @@ Parent: [CueLoop Documentation](../index.md) - **Impact:** Silent failure in daemon session isolation - **Fix:** Check `setsid()` return value and log on failure: `if libc::setsid() == -1 { log::warn!("setsid failed: {}", std::io::Error::last_os_error()); }` ---- ### COMPLEXITY & COGNITIVE LOAD @@ -139,7 +134,6 @@ Parent: [CueLoop Documentation](../index.md) - **Impact:** Regression risk on error handling changes - **Fix:** Consider a macro-driven approach or separate the `Display` impl into `runner/error/display.rs` ---- ### CODE QUALITY @@ -160,7 +154,6 @@ Parent: [CueLoop Documentation](../index.md) - **Impact:** Potential runtime crash if the invariant is violated - **Fix:** Return an error or no-op instead of panicking: `Ok(())` with a `log::warn!` ---- ### ERROR HANDLING @@ -178,7 +171,6 @@ Parent: [CueLoop Documentation](../index.md) - **Impact:** Future readers may wonder if the branch was forgotten - **Fix:** Add `// Intentional: success requires no action` comments ---- ### RESOURCE MANAGEMENT @@ -190,7 +182,6 @@ Parent: [CueLoop Documentation](../index.md) ✅ **[Temp Cleanup]** Startup runs `cleanup_default_temp_dirs` with configurable retention. ---- ### PERFORMANCE @@ -204,7 +195,6 @@ Parent: [CueLoop Documentation](../index.md) - **Impact:** Stale secrets won't be redacted if they change during process lifetime; memory grows with env size - **Fix:** Acceptable for a CLI tool — process lifetime is bounded. No action needed. ---- ### TESTING @@ -223,7 +213,6 @@ Parent: [CueLoop Documentation](../index.md) ✅ **[Integration Test Suite]** 176 integration test files with ~28K LOC provide substantial end-to-end coverage. ---- ### OBSERVABILITY @@ -235,7 +224,6 @@ Parent: [CueLoop Documentation](../index.md) - **Impact:** Difficult to diagnose streaming issues without RUST_LOG=debug - **Fix:** Add debug logging for session ID extraction, stream buffer growth, and timeout checkpoint transitions ---- ### CONFIGURATION @@ -245,7 +233,6 @@ Parent: [CueLoop Documentation](../index.md) ✅ **[JSONC Support]** Both JSON and JSONC config files supported with comments. ---- ### SHELL SCRIPTS @@ -264,7 +251,6 @@ Parent: [CueLoop Documentation](../index.md) - **Impact:** Undefined variable usage or failed commands could go undetected in library functions - **Fix:** Add `set -euo pipefail` to all library scripts, or add a guard: `[[ $- == *e* ]] || set -e` to inherit the caller's strict mode only if available. Given these are sourced libraries, adding `set -euo pipefail` at the top is safest and most explicit. ---- ## Remediation Roadmap @@ -310,7 +296,6 @@ Parent: [CueLoop Documentation](../index.md) 10. **Proactive file decomposition** — split remaining 31 files in the 400-500 LOC range before they breach the hard limit. Prioritize `cli/scan.rs`, `cli/machine/task.rs`, `commands/init/writers.rs`. ---- ## Appendix: Top 20 Largest Non-Test Source Files diff --git a/docs/features/README.md b/docs/features/README.md index e7c5a3ef..3ac6a843 100644 --- a/docs/features/README.md +++ b/docs/features/README.md @@ -1,188 +1,95 @@ -# CueLoop Features Documentation -Status: Active -Owner: Maintainers -Source of truth: this document for its stated scope -Parent: [CueLoop Documentation](../index.md) +# Feature guides +Status: Active +Owner: Maintainers +Source of truth: index for `docs/features/` +Parent: [Documentation index](../index.md) -Welcome to the CueLoop features documentation. This index provides organized navigation to all feature guides, from core concepts to advanced integration options. +Feature docs describe one capability each. Start from [Documentation index](../index.md) if you are new; use this page to jump by topic. ---- +## Core -## Overview +| Guide | Topics | +| --- | --- | +| [Phases](phases.md) | 1/2/3-phase execution | +| [Queue](queue.md) | `queue.jsonc`, validation, operations | +| [Tasks](tasks.md) | Task index → schema, lifecycle, operations | +| [Dependencies](dependencies.md) | `depends_on`, DAG, critical path | +| [Context](context.md) | RepoPrompt / context building | -CueLoop is a Rust CLI for running AI agent loops against a structured JSON task queue. The features documentation covers all major capabilities, configuration options, and workflows. - ---- - -## Quick Start - -New to CueLoop? Start here: - -- **[Quick Start Guide](../quick-start.md)** — Get up and running in minutes -- **[CLI Reference](../cli.md)** — Complete command-line documentation -- **[Configuration](../configuration.md)** — Full configuration reference - ---- - -## Core Concepts - -Understand the fundamental building blocks of CueLoop: - -| Document | Description | -|----------|-------------| -| **[Phases](./phases.md)** | Multi-phase execution workflow (Plan → Implement → Review) | -| **[Queue](./queue.md)** | Task queue management, lifecycle, and operations | -| **[Dependencies](./dependencies.md)** | Task relationships, DAG execution, and critical path analysis | -| **[Context](./context.md)** | RepoPrompt integration and context building | -| **[Tasks](./tasks.md)** | Task system index with split schema, lifecycle, relationships, and operations references | - ---- +Task detail pages: [task-schema](task-schema.md), [task-lifecycle](task-lifecycle.md), [task-operations](task-operations.md), [task-relationships](task-relationships.md). ## Execution -Learn how CueLoop executes tasks and manages the execution lifecycle: - -| Document | Description | -|----------|-------------| -| **[Runners](./runners.md)** | AI runner orchestration (Claude, Codex, Kimi, Gemini, etc.) | -| **[Parallel](./parallel.md)** | Parallel task execution with direct push integration | -| **[Session Management](./session-management.md)** | Crash recovery and session resumption | -| **[Supervision](./supervision.md)** | CI gate enforcement, git operations, and human-in-the-loop oversight | - ---- - -## Integration - -Connect CueLoop to external systems and notifications: - -| Document | Description | -|----------|-------------| -| **[Webhooks](./webhooks.md)** | HTTP event notifications for Slack, Discord, CI/CD | -| **[Plugins](./plugins.md)** | Custom runner and processor plugins | -| **[Notifications](./notifications.md)** | Desktop notifications and sound alerts | -| **[Import/Export](./import-export.md)** | Queue import/export formats and workflows | - ---- - -## Workflow - -Tools for managing and monitoring your development workflow: - -| Document | Description | -|----------|-------------| -| **[App (macOS)](./app.md)** | macOS SwiftUI app for interactive task management | -| **[Scan](./scan.md)** | AI-powered repository scanning for task discovery | -| **[Daemon and Watch](./daemon-and-watch.md)** | Background execution and automatic task detection, with focused daemon, watch, operations, and troubleshooting guides | - ---- - -## Configuration - -Detailed configuration guides for specific features: - -| Document | Description | -|----------|-------------| -| **[Configuration](./configuration.md)** | Feature-level configuration map and operator guidance | -| **[Agent and Runner Configuration](./configuration-agent.md)** | Runner, model, phase, CI gate, permission, and retry settings | -| **[Queue and Parallel Configuration](./configuration-operations.md)** | Queue paths, task aging, auto-archive, and parallel workspace settings | -| **[Integration and Profile Configuration](./configuration-integrations.md)** | Notifications, webhooks, plugins, profiles, and environment variables | -| **[Complete Configuration Example](./configuration-example.md)** | Long assembled configuration sample | -| **[Profiles](./profiles.md)** | Configuration profiles for quick workflow switching | -| **[Prompts](./prompts.md)** | Custom prompt templates and overrides | -| **[Migrations](./migrations.md)** | Configuration and data migration guide | - ---- - -## Security - -Security-related documentation: - -| Document | Description | -|----------|-------------| -| **[Security Features](./security.md)** | Security features and configuration | -| **[Security Policy](../../SECURITY.md)** — Main security policy and vulnerability reporting | - ---- - -## Reference - -Additional reference documentation: - -| Document | Description | -|----------|-------------| -| **[CLI Reference](../cli.md)** | Complete command-line documentation | -| **[Error Handling](../error-handling.md)** | Patterns and best practices | -| **[Environment](../environment.md)** | Environment variables reference | -| **[Tasks](./tasks.md)** | Task system index and focused task reference pages | -| **[Queue and Tasks](../queue-and-tasks.md)** | Combined queue and task reference | -| **[Workflow](../workflow.md)** | High-level workflow documentation | -| **[Releasing](../releasing.md)** | Release process documentation | - ---- - -## Schema Reference - -CueLoop uses JSON schemas for validation: +| Guide | Topics | +| --- | --- | +| [Runners](runners.md) | Runner CLIs and overrides | +| [Parallel](parallel.md) | Parallel workers and integration | +| [Session management](session-management.md) | Resume after crash | +| [Supervision](supervision.md) | CI gates, git, human-in-the-loop | -- **[Config Schema](../../schemas/config.schema.json)** — Configuration schema -- **[Queue Schema](../../schemas/queue.schema.json)** — Queue and task schema -- **[Machine Schema](../../schemas/machine.schema.json)** — Machine / structured integration schema +## Integrations ---- +| Guide | Topics | +| --- | --- | +| [Webhooks](webhooks.md) | HTTP events | +| [Plugins](plugins.md) | Custom runners/processors | +| [Notifications](notifications.md) | Desktop alerts | +| [Import/export](import-export.md) | Queue interchange formats | -## Documentation by Use Case +Plugin detail: [plugins/](plugins/) (architecture, protocols, operations, security). -### I want to... +## Workflow tools -**Get started quickly** -- [Quick Start Guide](../quick-start.md) -- [App (macOS)](./app.md) — Interactive interface +| Guide | Topics | +| --- | --- | +| [App](app.md) | macOS SwiftUI client | +| [Scan](scan.md) | Repository discovery | +| [Daemon and watch](daemon-and-watch.md) | Background automation | -**Configure my runner** -- [Runners](./runners.md) — Runner-specific setup -- [Configuration](../configuration.md) — General configuration -- [Profiles](./profiles.md) — Workflow presets +Daemon/watch detail: [daemon-watch/](daemon-watch/). -**Set up parallel execution** -- [Parallel](./parallel.md) — Parallel mode -- [Configuration](../configuration/queue-and-parallel.md#parallel-configuration) — Parallel settings +## Configuration (feature-level) -**Integrate with Slack/Discord** -- [Webhooks](./webhooks.md) — Webhook setup -- [Notifications](./notifications.md) — Desktop notifications +| Guide | Topics | +| --- | --- | +| [Configuration](configuration.md) | Feature config map | +| [Configuration agent](configuration-agent.md) | Runners, phases, CI gate | +| [Configuration operations](configuration-operations.md) | Queue paths, parallel | +| [Configuration integrations](configuration-integrations.md) | Webhooks, plugins, profiles | +| [Profiles](profiles.md) | Named presets | +| [Prompts](prompts.md) | Templates and overrides | +| [Migrations](migrations.md) | Config/data migration | -**Automate task detection** -- [Watch Mode](./daemon-watch/watch.md) — Watch mode for TODO/FIXME/HACK/XXX comments -- [Daemon and Watch](./daemon-and-watch.md) — Background workflow overview -- [Scan](./scan.md) — Repository scanning +Repo-wide config hub: [Configuration](../configuration.md). Example: [configuration-example](configuration-example.md). -**Handle failures and recovery** -- [Session Management](./session-management.md) — Resume interrupted tasks -- [Phases](./phases.md) — Human-in-the-loop review (supervision workflows) -- [Error Handling](../error-handling.md) — Error patterns +## Security and reference -**Manage task dependencies** -- [Dependencies](./dependencies.md) — Dependency relationships -- [Queue](./queue.md) — Queue operations +| Guide | Topics | +| --- | --- | +| [Security](security.md) | Feature security controls | +| [SECURITY.md](../../SECURITY.md) | Vulnerability reporting | -**Customize prompts** -- [Prompts](./prompts.md) — Prompt customization -- [Phases](./phases.md) — Phase-specific prompts +Also: [CLI](../cli.md), [Error handling](../error-handling.md), [Environment](../environment.md), [Machine contract](../machine-contract.md). -**Migrate configurations** -- [Migrations](./migrations.md) — Migration guide -- `cueloop migrate` command in [CLI](../cli.md) +## Schemas ---- +- [config.schema.json](../../schemas/config.schema.json) +- [queue.schema.json](../../schemas/queue.schema.json) +- [machine.schema.json](../../schemas/machine.schema.json) -## Contributing to Documentation +Regenerate after source changes: `make generate`. -When adding new features or updating existing ones: +## By goal -1. Update the relevant feature document in `docs/features/` -2. Update this index if adding a new feature category -3. Update `docs/index.md` with any new top-level references -4. Run `make agent-ci` to validate docs-only checks, including markdown links and documented path guards +| I want to… | Read | +| --- | --- | +| Run my first task | [Quick start](../quick-start.md) | +| Configure a runner | [Runners](runners.md), [Configuration](../configuration.md) | +| Run tasks in parallel | [Parallel](parallel.md) | +| Notify Slack/Discord | [Webhooks](webhooks.md) | +| Auto-detect TODOs | [Watch](daemon-watch/watch.md) | +| Resume a crashed run | [Session management](session-management.md) | +| Customize prompts | [Prompts](prompts.md) | -See [Contributing Guidelines](../../CONTRIBUTING.md) for more details. +Legacy hubs: [Queue and tasks](../queue-and-tasks.md), [Workflow](../workflow.md). diff --git a/docs/features/configuration-agent.md b/docs/features/configuration-agent.md index 4cdd6ddd..56eed1b8 100644 --- a/docs/features/configuration-agent.md +++ b/docs/features/configuration-agent.md @@ -6,7 +6,6 @@ Parent: [Configuration Feature Guide](configuration.md) Use this guide when choosing how CueLoop invokes AI runners. For exact field names, defaults, and validation rules, use [Agent Configuration](../configuration/agent-and-runners.md#agent-configuration). ---- ## Common Decisions @@ -24,7 +23,6 @@ Related feature docs: - [Phases](./phases.md) - [Supervision](./supervision.md) ---- ## Minimal Safe Baseline @@ -45,7 +43,6 @@ Related feature docs: Start with the CI gate off until you have a repo-local argv command you trust; enable it when you are ready for CueLoop to enforce that check before completion. ---- ## Runner Binary Overrides @@ -59,7 +56,6 @@ Canonical details: - [Agent Configuration](../configuration/agent-and-runners.md#agent-configuration) - [Cursor SDK setup](../configuration/agent-and-runners.md#cursor-sdk-setup) ---- ## Permission and Publication Safety @@ -74,7 +70,6 @@ Treat permissive modes (`yolo`, bypass-style approvals, publish-on-run) as high- > Note: Codex approval behavior is managed through Codex-native config. CueLoop does not force Codex approval flags. ---- ## CI Gate @@ -85,7 +80,6 @@ Treat permissive modes (`yolo`, bypass-style approvals, publish-on-run) as high- Canonical details: [Agent Configuration](../configuration/agent-and-runners.md#agent-configuration). ---- ## Runner CLI Normalization @@ -105,7 +99,6 @@ Typical controls: Canonical reference: [agent.runner_cli](../configuration/agent-and-runners.md#agentrunner_cli). ---- ## Phase Overrides and Retry @@ -133,7 +126,6 @@ Canonical references: - [agent.phase_overrides](../configuration/agent-and-runners.md#agentphase_overrides) - [agent.runner_retry](../configuration/agent-and-runners.md#agentrunner_retry) ---- ## See Also diff --git a/docs/features/configuration-example.md b/docs/features/configuration-example.md index 620f8926..d5a8dbb2 100644 --- a/docs/features/configuration-example.md +++ b/docs/features/configuration-example.md @@ -135,7 +135,3 @@ Here's a comprehensive example demonstrating all configuration sections: } } ``` - ---- - - diff --git a/docs/features/configuration-integrations.md b/docs/features/configuration-integrations.md index 604e9cb4..085108ee 100644 --- a/docs/features/configuration-integrations.md +++ b/docs/features/configuration-integrations.md @@ -6,7 +6,6 @@ Parent: [Configuration Feature Guide](configuration.md) Use this guide when configuring notifications, webhooks, plugins, profiles, and environment-variable substitution. Exact fields and defaults live in [Main Configuration Reference](../configuration.md). ---- ## Notifications @@ -17,7 +16,6 @@ Start with: - [Notifications feature guide](./notifications.md) - [Notification configuration reference](../configuration/notifications-and-webhooks.md#notification-configuration) ---- ## Webhooks @@ -40,7 +38,6 @@ References: - [Webhooks feature guide](./webhooks.md) - [Webhook configuration reference](../configuration/notifications-and-webhooks.md#webhook-configuration) ---- ## Plugins @@ -56,7 +53,6 @@ References: - [Plugin configuration reference](../configuration/plugins-and-profiles.md#plugin-configuration) - [Repo execution trust](../configuration/trust-and-precedence.md#repo-execution-trust) ---- ## Profiles @@ -67,7 +63,6 @@ References: - [Profiles feature guide](./profiles.md) - [Profiles configuration reference](../configuration/plugins-and-profiles.md#profiles) ---- ## Environment Variables @@ -79,7 +74,6 @@ Unsupported path override variables: - `CUELOOP_QUEUE_PATH_OVERRIDE` - `CUELOOP_DONE_PATH_OVERRIDE` ---- ## Example @@ -97,7 +91,6 @@ Unsupported path override variables: } ``` ---- ## See Also diff --git a/docs/features/configuration-operations.md b/docs/features/configuration-operations.md index 1db432af..5e37fdb9 100644 --- a/docs/features/configuration-operations.md +++ b/docs/features/configuration-operations.md @@ -6,7 +6,6 @@ Parent: [Configuration Feature Guide](configuration.md) Use this guide when configuring CueLoop queue files, task aging, archive behavior, and parallel worker workspaces. Exact fields and defaults live in [Queue Configuration](../configuration/queue-and-parallel.md#queue-configuration) and [Parallel Configuration](../configuration/queue-and-parallel.md#parallel-configuration). ---- ## Queue File Locations @@ -26,7 +25,6 @@ Canonical details: - [Queue Configuration](../configuration/queue-and-parallel.md#queue-configuration) - [Queue and Tasks](../queue-and-tasks.md) ---- ## Task ID and Aging Settings @@ -40,7 +38,6 @@ Common queue hygiene settings: Invariant: `warning_days < stale_days < rotten_days`. ---- ## Auto-Archive @@ -50,7 +47,6 @@ Invariant: `warning_days < stale_days < rotten_days`. - `0`: archive immediately when sweep runs - `N > 0`: archive when `completed_at` is at least `N` days old ---- ## Parallel Workers @@ -66,7 +62,6 @@ If `workspace_root` is inside the repo, keep it gitignored. Current parallel mode does not use legacy PR-era keys; prefer the direct-push model documented in [Parallel](./parallel.md). ---- ## Example @@ -85,7 +80,6 @@ Current parallel mode does not use legacy PR-era keys; prefer the direct-push mo } ``` ---- ## See Also diff --git a/docs/features/configuration.md b/docs/features/configuration.md index 5868cbe2..efed3677 100644 --- a/docs/features/configuration.md +++ b/docs/features/configuration.md @@ -11,7 +11,6 @@ CueLoop configuration is documented in two layers: Use this page to decide where a setting belongs. Use the main reference when you need exact field names, defaults, and validation rules. ---- ## Configuration Map @@ -23,7 +22,6 @@ Use this page to decide where a setting belongs. Use the main reference when you | Configure plugins/webhooks/notifications/profiles | [Integrations and profiles](configuration-integrations.md) | [Plugin Configuration](../configuration/plugins-and-profiles.md#plugin-configuration) | | Keep a complete example nearby | [Complete Configuration Example](configuration-example.md) | [Config Schema](../../schemas/config.schema.json) | ---- ## Config Files and Locations @@ -43,7 +41,6 @@ cueloop config schema cueloop config profiles list ``` ---- ## Precedence at a Glance @@ -54,7 +51,6 @@ For exact behavior and edge cases, see: - [Precedence](../configuration/trust-and-precedence.md#precedence) - [Profiles](../configuration/plugins-and-profiles.md#profiles) ---- ## Trust and Safety @@ -78,7 +74,6 @@ For the allowed file/glob contract and invalid examples such as `node_modules/*` Canonical details: [Repo execution trust](../configuration/trust-and-precedence.md#repo-execution-trust). ---- ## JSONC and Validation Basics @@ -90,7 +85,6 @@ CueLoop supports JSONC (`.jsonc`) for runtime config and queue files: Current configuration version is `2`. Prefer canonical validation/error details from [Configuration](../configuration.md). ---- ## Feature Guides @@ -101,7 +95,6 @@ Use these focused pages for feature-level configuration decisions: - [Integration and Profile Configuration](configuration-integrations.md) - [Complete Configuration Example](configuration-example.md) ---- ## See Also diff --git a/docs/features/context.md b/docs/features/context.md index 32a2ac5a..be80f1a3 100644 --- a/docs/features/context.md +++ b/docs/features/context.md @@ -9,7 +9,6 @@ Parent: [Feature Documentation](README.md) The Context system in CueLoop generates and maintains an `AGENTS.md` file that documents project conventions, build commands, testing guidelines, and workflow contracts for AI agents working on the codebase. ---- ## Overview @@ -30,7 +29,6 @@ The Context system in CueLoop generates and maintains an `AGENTS.md` file that d - **Section-based updates**: Add new learnings without regenerating the entire file - **Validation**: Ensure AGENTS.md stays complete and up-to-date ---- ## Generating Context @@ -84,7 +82,6 @@ $ cueloop context init --interactive ? Preview and confirm before writing? › Yes ``` ---- ## Project Type Detection @@ -112,7 +109,6 @@ cueloop context init --project-type rust cueloop context init --project-type generic ``` ---- ## AGENTS.md Structure @@ -191,7 +187,6 @@ Command source: No repo-specific command contract detected; entries below start Projects that want stricter local rules (for example mandatory module docs or a Makefile-only build contract) should edit the generated `AGENTS.md` and state that policy explicitly instead of relying on defaults. ---- ## Updating Context @@ -264,7 +259,6 @@ Update files use markdown sections that match AGENTS.md section names: Only sections specified with `--section` (or all sections if none specified) will be processed. ---- ## Validating Context @@ -298,7 +292,6 @@ cueloop context validate --path docs/AGENTS.md - `0`: Validation passed - Non-zero: Validation failed (missing sections or file not found) ---- ## Context in Prompts @@ -392,7 +385,6 @@ $ cueloop doctor ✓ runner/agents_md: AGENTS.md configured and readable ``` ---- ## Best Practices @@ -450,7 +442,6 @@ cueloop context update --section troubleshooting cueloop context validate --strict ``` ---- ## Template Reference @@ -491,7 +482,6 @@ Templates use these placeholders that are replaced at generation time: | `{timestamp}` | Generation timestamp (RFC3339) | | `{template_version}` | Template version for tracking | ---- ## Troubleshooting @@ -540,7 +530,6 @@ The `update` command intentionally appends to preserve existing content. To repl 1. Use `cueloop context init --force` to regenerate 2. Or manually edit the file ---- ## See Also diff --git a/docs/features/daemon-watch/daemon.md b/docs/features/daemon-watch/daemon.md index 30cb5231..1227f00d 100644 --- a/docs/features/daemon-watch/daemon.md +++ b/docs/features/daemon-watch/daemon.md @@ -23,7 +23,6 @@ Daemon mode runs CueLoop as a background service that continuously monitors the > **Platform Support**: Daemon mode is Unix-only. On Windows, use `cueloop run loop --continuous` directly or configure a Windows service. ---- ### Commands @@ -101,7 +100,6 @@ Daemon is running Command: cueloop daemon serve --empty-poll-ms 30000 --wait-poll-ms 1000 ``` ---- ### Behavior @@ -159,7 +157,6 @@ The daemon maintains state in `.cueloop/cache/daemon.json`: **Lock File**: `.cueloop/cache/daemon.lock` prevents multiple daemons from starting simultaneously. ---- ### Configuration @@ -201,7 +198,6 @@ This triggers: } ``` ---- ### Service Templates @@ -291,7 +287,6 @@ launchctl list | grep com.cueloop.daemon launchctl unload ~/Library/LaunchAgents/com.cueloop.daemon.plist ``` ---- ### Continuous Mode @@ -320,7 +315,6 @@ cueloop run loop --wait-when-empty - Responds to Ctrl+C when running in foreground - Polls at `--empty-poll-ms` interval ---- ### Wait When Blocked @@ -352,7 +346,6 @@ cueloop run loop --wait-when-blocked cueloop run loop --wait-when-blocked --wait-timeout-seconds 600 --notify-when-unblocked ``` ---- ### Graceful Shutdown @@ -391,7 +384,6 @@ Daemon did not stop within 10 seconds. PID: 12345. You may need to kill it manually with `kill -9 12345` ``` ---- ## See Also diff --git a/docs/features/daemon-watch/operations.md b/docs/features/daemon-watch/operations.md index 7fc125f8..322a9b22 100644 --- a/docs/features/daemon-watch/operations.md +++ b/docs/features/daemon-watch/operations.md @@ -38,7 +38,6 @@ tmux new-session -d -s cueloop-watch "cueloop watch --auto-queue --close-removed tmux attach -t cueloop-watch ``` ---- ## See Also diff --git a/docs/features/daemon-watch/troubleshooting.md b/docs/features/daemon-watch/troubleshooting.md index 41f0e6a3..8054034d 100644 --- a/docs/features/daemon-watch/troubleshooting.md +++ b/docs/features/daemon-watch/troubleshooting.md @@ -42,7 +42,6 @@ rm -f .cueloop/cache/stop_requested cueloop daemon start ``` ---- ## See Also diff --git a/docs/features/daemon-watch/watch.md b/docs/features/daemon-watch/watch.md index 31a6b0ca..895e89d4 100644 --- a/docs/features/daemon-watch/watch.md +++ b/docs/features/daemon-watch/watch.md @@ -23,7 +23,6 @@ Watch mode monitors source files for changes and automatically creates tasks fro **CURRENTLY IMPLEMENTED BEHAVIOR**: Full implementation with fingerprint-based deduplication, debounced file processing, and comment reconciliation. ---- ### Commands @@ -56,7 +55,6 @@ cueloop watch --debounce-ms 1000 cueloop watch --ignore-patterns "vendor/,target/,node_modules/" ``` ---- ### Triggers @@ -98,7 +96,6 @@ Comments are matched case-insensitively with flexible separators: // TODO fix this ``` ---- ### Debouncing @@ -141,7 +138,6 @@ The event loop: 3. Updates `last_event` timestamp 4. Processes when `now - last_event >= debounce_duration` ---- ### Configuration @@ -208,7 +204,6 @@ cueloop watch --comments todo,fixme cueloop watch --comments todo,fixme,hack ``` ---- ### Deduplication @@ -246,7 +241,6 @@ pub fn generate_comment_fingerprint(content: &str) -> String { - Whitespace changes (normalization handles this) - Case changes (normalization handles this) ---- ### Comment Reconciliation @@ -289,7 +283,6 @@ cueloop watch --auto-queue --close-removed # 3. Remove the TODO comment → Task auto-closed ``` ---- ### Task Metadata @@ -318,7 +311,6 @@ Watch-created tasks include structured metadata in `custom_fields`: | `watch.fingerprint` | SHA256 prefix for deduplication | | `watch.version` | Metadata format version | ---- ### Use Cases @@ -362,7 +354,6 @@ cueloop watch --auto-queue --close-removed --patterns "*.rs" cueloop queue list --tag watch --format json | jq '.tasks | group_by(.custom_fields."watch.comment_type") | map({type: .[0].custom_fields."watch.comment_type", count: length})' ``` ---- ## See Also diff --git a/docs/features/import-export.md b/docs/features/import-export.md index 007020f0..6ea53e8e 100644 --- a/docs/features/import-export.md +++ b/docs/features/import-export.md @@ -9,7 +9,6 @@ Parent: [Feature Documentation](README.md) CueLoop's import/export system enables bulk operations, cross-repository migration, and integration with external tools. Tasks can be exported to various formats for reporting or external processing, and imported from CSV, TSV, or JSON for bulk backlog seeding. ---- ## Overview @@ -22,7 +21,6 @@ The import/export system provides: - **GitHub integration**: Publish tasks directly as GitHub issues - **Round-trip support**: Export and re-import without data loss ---- ## Export @@ -180,7 +178,6 @@ GitHub format produces Markdown optimized for issue bodies: Multiple tasks are separated by horizontal rules (`---`). ---- ## Import @@ -343,7 +340,6 @@ Imported tasks. parsed 5 task(s); imported 5; renamed 2 task(s) OLD-002 -> RQ-0043 ``` ---- ## Round-trip @@ -398,7 +394,6 @@ cueloop queue import --format csv --input tasks.csv --on-duplicate rename **Not preserved in CSV/TSV:** - Task order (new tasks are positioned per queue policy) ---- ## GitHub Issue Publishing @@ -462,7 +457,6 @@ After publishing, these custom fields are set: To re-publish (update) an issue, run the command again. CueLoop detects the existing URL and updates rather than creates. ---- ## Use Cases @@ -522,7 +516,6 @@ cueloop queue export --format json --priority critical | \ xargs -I {} cueloop queue issue publish {} --label critical ``` ---- ## Best Practices @@ -534,7 +527,6 @@ cueloop queue export --format json --priority critical | \ 6. **Use Markdown for human-readable reports** - great for documentation 7. **Check import reports** - review rename mappings and skip counts ---- ## Troubleshooting diff --git a/docs/features/migrations.md b/docs/features/migrations.md index 671de388..2b58c5ae 100644 --- a/docs/features/migrations.md +++ b/docs/features/migrations.md @@ -7,7 +7,6 @@ Parent: [Feature Documentation](README.md) The migration system manages breaking changes to configuration keys, file formats, and project structure. It provides automated detection, safe application with backup/rollback capability, and preserves JSONC comments during migrations. ---- ## Table of Contents @@ -21,7 +20,6 @@ The migration system manages breaking changes to configuration keys, file format 8. [Breaking Changes Reference](#breaking-changes-reference) 9. [Implementation Details](#implementation-details) ---- ## Overview @@ -48,7 +46,6 @@ README template updates are handled by `cueloop init` and agent-facing write-ena - **History-Tracked**: All applied migrations are recorded in `.cueloop/cache/migrations.jsonc` - **Scoped Renames**: Config key renames are scoped to their parent object (e.g., `parallel.worktree_root` only renames within `parallel` objects) ---- ## Migration Types @@ -158,7 +155,6 @@ MigrationType::ReadmeUpdate { - Replaces local README drift because the file is CueLoop-owned/generated - Only applicable if current README version < target version ---- ## Migration Registry @@ -209,7 +205,6 @@ Migration { }, ``` ---- ## History Tracking @@ -247,7 +242,6 @@ Migration history is stored in `.cueloop/cache/migrations.jsonc`. - **Atomic writes**: Uses atomic file writes to prevent corruption - **Git-ignored**: The entire `.cueloop/cache/` directory should be gitignored ---- ## CLI Commands @@ -382,7 +376,6 @@ Examples: cueloop migrate status # Show detailed migration status ``` ---- ## Automatic Migrations @@ -408,7 +401,6 @@ Potential future enhancements may include: 3. **CI integration**: Use `cueloop migrate --check` in CI to fail builds if migrations are needed 4. **Version control**: Review migration changes before committing ---- ## Manual Migrations @@ -486,7 +478,6 @@ if ! cueloop migrate --check; then fi ``` ---- ## Breaking Changes Reference @@ -535,7 +526,6 @@ MigrationType::ConfigKeyRename { > **Important:** State files are not migrated and may need to be deleted if incompatible. For example, parallel mode state files (`.cueloop/cache/parallel/state.json`) may contain references to old config keys. ---- ## Implementation Details @@ -622,7 +612,6 @@ cargo test -p cueloop migration 4. **History validation**: Migration history schema version is checked 5. **Confirmation prompts**: `--apply` requires user confirmation (unless `--force`) ---- ## Related Documentation diff --git a/docs/features/notifications.md b/docs/features/notifications.md index 74bff44e..93e40aed 100644 --- a/docs/features/notifications.md +++ b/docs/features/notifications.md @@ -9,7 +9,6 @@ Parent: [Feature Documentation](README.md) CueLoop provides a cross-platform desktop notification system that alerts you when tasks complete, fail, or when loop execution finishes. Notifications help you stay informed about long-running tasks without constantly monitoring the terminal. ---- ## Overview @@ -26,7 +25,6 @@ Notifications are designed to be: - **Cross-platform**: Native notifications on macOS, Linux, and Windows - **Optional sound**: Audible alerts can accompany visual notifications ---- ## Configuration @@ -112,7 +110,6 @@ Settings are resolved in this order (highest to lowest): } ``` ---- ## Platform Support @@ -210,7 +207,6 @@ alsa-utils # For aplay (fallback) On platforms not explicitly supported, notifications are silently skipped with a debug log entry. The build can disable the `notifications` feature to compile without notification support entirely. ---- ## Sound Support @@ -269,7 +265,6 @@ Platform-specific paths should be used: **CURRENTLY IMPLEMENTED BEHAVIOR:** Sound failures are logged at debug level using `log::debug!()` and do not affect notification display or task execution. This matches the intended behavior. ---- ## CLI Overrides @@ -324,7 +319,6 @@ If you need different settings for completion vs failure, use the specific flags cueloop run one --notify --no-notify-fail ``` ---- ## Webhook Notifications @@ -373,7 +367,6 @@ cueloop run loop --wait-when-blocked --notify-when-unblocked This sends both desktop and webhook notifications when a previously blocked task becomes ready to run. ---- ## When Notifications Fire @@ -437,7 +430,6 @@ Understanding the exact timing of notifications helps you configure them appropr When `suppress_when_active` is `true`, desktop notifications are suppressed while the macOS app is active. ---- ## Practical Examples @@ -541,7 +533,6 @@ cueloop run loop --no-notify --no-notify-fail cueloop run loop --notify --notify-fail ``` ---- ## Troubleshooting @@ -594,7 +585,6 @@ cargo build --no-default-features This disables the `notifications` feature flag, making all notification functions no-ops. ---- ## Related Documentation diff --git a/docs/features/parallel.md b/docs/features/parallel.md index 8d476275..31f76713 100644 --- a/docs/features/parallel.md +++ b/docs/features/parallel.md @@ -13,7 +13,6 @@ Parallel execution runs multiple tasks concurrently in isolated git workspace cl > **CLI Only**: Parallel execution is available only via CLI (`cueloop run loop --parallel [N]`). ---- ## Table of Contents @@ -28,7 +27,6 @@ Parallel execution runs multiple tasks concurrently in isolated git workspace cl 9. [Workflow](#workflow) 10. [Monitoring](#monitoring) ---- ## Overview @@ -78,7 +76,6 @@ Before enabling it, confirm that: - your repo can tolerate concurrent workspace clones and repeated rebase/push attempts - you have intentionally selected a publish mode that matches that risk ---- ## Architecture @@ -141,7 +138,6 @@ Before enabling it, confirm that: - Runs CI gates - Pushes to origin ---- ## Workspace Management @@ -172,7 +168,6 @@ Workspace cleanup behavior: - **Failed workers**: Cleaned immediately after worker failure. - **Blocked workers**: Retained for explicit operator retry (`cueloop run parallel retry --task ...`). ---- ## Integration Loop @@ -221,7 +216,6 @@ Parallel workers do not mutate shared queue/done files for newly discovered foll - Irreparable queue/done validation failures - Persistent CI failure after retry exhaustion ---- ## Configuration @@ -261,7 +255,6 @@ The following settings were removed in the direct-push rewrite: - `delete_branch_on_merge` - No longer applicable - `merge_runner` - No longer applicable ---- ## State Management @@ -313,7 +306,6 @@ State files are automatically migrated from v2 (PR-based) to v3: - In-flight workers are mapped to new schema - Workers in terminal PR states are marked as `failed` ---- ## Operations Commands @@ -345,7 +337,6 @@ This: 3. Preserves push attempt count (for debugging) 4. The worker will be picked up on the next `cueloop run loop --parallel` ---- ## Limitations @@ -369,7 +360,6 @@ If your target branch has protected branch policies: - This results in `BlockedPush` status - Use `cueloop run parallel retry` after resolving branch protection issues ---- ## Workflow @@ -402,7 +392,6 @@ When workers encounter conflicts: 4. **Validation**: Worker verifies zero unresolved conflicts before continuing 5. **Retry**: If resolution fails after max attempts, worker transitions to `blocked_push` ---- ## Monitoring @@ -461,7 +450,6 @@ git log --oneline -10 cueloop run parallel retry --task ``` ---- ## Troubleshooting @@ -484,7 +472,6 @@ cueloop run parallel retry --task **Workspace disk space** - Workspaces accumulate over time. Run `cueloop cleanup` or adjust `workspace_retention_hours`. ---- ## See Also diff --git a/docs/features/plugins.md b/docs/features/plugins.md index 487bd084..7baf73b9 100644 --- a/docs/features/plugins.md +++ b/docs/features/plugins.md @@ -10,7 +10,6 @@ Purpose: Entry point for CueLoop's plugin system, including custom runners and t > ⚠️ **Critical security warning:** Plugins are not sandboxed. Enabling a plugin grants full system access equivalent to running arbitrary code. Only enable plugins from trusted sources. See [Plugin Security](plugins/security.md). ---- ## Overview diff --git a/docs/features/plugins/architecture.md b/docs/features/plugins/architecture.md index 91886d13..df3f2cbf 100644 --- a/docs/features/plugins/architecture.md +++ b/docs/features/plugins/architecture.md @@ -6,7 +6,6 @@ Parent: [CueLoop Plugin System](../plugins.md) Purpose: Explain how CueLoop discovers plugins and validates plugin manifests. ---- ## Discovery Layout diff --git a/docs/features/plugins/examples.md b/docs/features/plugins/examples.md index 4975ecd0..36f49a12 100644 --- a/docs/features/plugins/examples.md +++ b/docs/features/plugins/examples.md @@ -6,7 +6,6 @@ Parent: [CueLoop Plugin System](../plugins.md) Purpose: Provide concrete runner and processor plugin examples that demonstrate the documented protocols. ---- ## Example 1: Custom Runner Plugin diff --git a/docs/features/plugins/operations.md b/docs/features/plugins/operations.md index 01043c77..e4e4061f 100644 --- a/docs/features/plugins/operations.md +++ b/docs/features/plugins/operations.md @@ -6,7 +6,6 @@ Parent: [CueLoop Plugin System](../plugins.md) Purpose: Show how operators scaffold, install, enable, configure, inspect, validate, and remove plugins. ---- ## Configure and Enable diff --git a/docs/features/plugins/processor-protocol.md b/docs/features/plugins/processor-protocol.md index a5d36c2d..bb0a043f 100644 --- a/docs/features/plugins/processor-protocol.md +++ b/docs/features/plugins/processor-protocol.md @@ -6,7 +6,6 @@ Parent: [CueLoop Plugin System](../plugins.md) Purpose: Define processor hook timing, inputs, ordering, environment, mutation rules, and failure behavior. ---- ## Hook Types diff --git a/docs/features/plugins/runner-protocol.md b/docs/features/plugins/runner-protocol.md index c48506a9..f8d679e5 100644 --- a/docs/features/plugins/runner-protocol.md +++ b/docs/features/plugins/runner-protocol.md @@ -6,7 +6,6 @@ Parent: [CueLoop Plugin System](../plugins.md) Purpose: Define the command-line, environment, streaming-output, and session contracts for runner plugins. ---- ## Runner Commands diff --git a/docs/features/plugins/security.md b/docs/features/plugins/security.md index ada02f15..b46be4e5 100644 --- a/docs/features/plugins/security.md +++ b/docs/features/plugins/security.md @@ -6,7 +6,6 @@ Parent: [CueLoop Plugin System](../plugins.md) Purpose: Explain the risks and required safety practices for enabling and running plugins. ---- > ⚠️ **Plugins are not sandboxed.** Enabling a plugin is equivalent to trusting it with full system access. diff --git a/docs/features/plugins/troubleshooting.md b/docs/features/plugins/troubleshooting.md index 65fe6705..cf27f45c 100644 --- a/docs/features/plugins/troubleshooting.md +++ b/docs/features/plugins/troubleshooting.md @@ -6,7 +6,6 @@ Parent: [CueLoop Plugin System](../plugins.md) Purpose: Help operators and plugin authors diagnose plugin discovery, manifest, runtime, and compatibility issues. ---- ## Debugging Commands diff --git a/docs/features/profiles.md b/docs/features/profiles.md index 46dea615..0ebe5308 100644 --- a/docs/features/profiles.md +++ b/docs/features/profiles.md @@ -9,7 +9,6 @@ Parent: [Feature Documentation](README.md) Purpose: Document CueLoop's configuration profiles feature for quick workflow switching between named `agent` presets. ---- ## Overview diff --git a/docs/features/prompts.md b/docs/features/prompts.md index 497ab6af..3ffd21c1 100644 --- a/docs/features/prompts.md +++ b/docs/features/prompts.md @@ -9,7 +9,6 @@ Parent: [Feature Documentation](README.md) Purpose: Comprehensive guide to CueLoop's prompt template system, including embedded defaults, override mechanisms, template variables, and prompt flow. ---- ## Overview @@ -66,7 +65,6 @@ CueLoop uses a sophisticated prompt system to guide AI agents through task execu └─────────────────────────────────────────────────────────────────┘ ``` ---- ## Embedded Defaults @@ -108,7 +106,6 @@ This ensures that: - Teams can incrementally customize only the prompts they need - Malformed override files are caught early ---- ## Prompt Overrides @@ -182,7 +179,6 @@ If an override is missing required placeholders, CueLoop fails fast with a clear Configured `agent.instruction_files` are prepended as authoritative content at the top of every prompt. CueLoop does not auto-inject `~/.codex/AGENTS.md` or repo `AGENTS.md`; prompt text should not imply otherwise. ---- ## Available Prompts @@ -305,7 +301,6 @@ Review body injected in Phase 3: **phase2_handoff_checklist.md**: Steps for 3-phase handoff; when `agent.ci_gate.enabled=false`, Phase 2 implementation and handoff still continue. **iteration_checklist.md**: Steps for refinement iterations; disabled CI gate configuration skips only the configured CI command/requirement, and iteration work continues. ---- ## Template Variables @@ -363,7 +358,6 @@ Escaped: $${LITERAL} or \${LITERAL} Environment variables are expanded before config values. ---- ## Project Type Guidance @@ -421,7 +415,6 @@ PromptTemplateId::WorkerPhase1 => PromptTemplate { }, ``` ---- ## RepoPrompt Integration @@ -474,7 +467,6 @@ If RepoPrompt MCP tools are unavailable, prefer the RepoPrompt CLI when it exist - `rp-cli` commonly uses `-e` to execute an expression such as `rp-cli -e 'tree'` ``` ---- ## Prompt Flow @@ -605,7 +597,6 @@ User Request ──► Load task_builder.md ──► Validate Required Placehol └──────────────────────────────────────────┘ ``` ---- ## Best Practices @@ -667,7 +658,6 @@ cueloop run --debug cat .cueloop/logs/debug.log | grep -A 50 "Rendered prompt" ``` ---- ## Reference diff --git a/docs/features/queue.md b/docs/features/queue.md index 10d0da90..81520994 100644 --- a/docs/features/queue.md +++ b/docs/features/queue.md @@ -19,7 +19,6 @@ The queue is the source of truth for active work in CueLoop. It manages tasks th - [Auto-Archive](#auto-archive) - [Aging](#aging) ---- ## Overview @@ -40,7 +39,6 @@ CueLoop uses two primary queue files: 4. **Dependency-Aware**: The queue understands task dependencies and validates them to prevent circular dependencies or broken references. ---- ## Queue File Format @@ -84,7 +82,6 @@ The `tasks` array contains all tasks in the queue. Tasks are processed in array } ``` ---- ## Task Lifecycle @@ -129,7 +126,6 @@ Tasks with status `done` or `rejected` **must** have: These tasks are eligible for archiving to `.cueloop/done.jsonc`. ---- ## Task Ordering @@ -165,7 +161,6 @@ When new tasks are added via `cueloop task \"...\"` (or `cueloop task build \".. This prevents new tasks from jumping ahead of work already in progress. ---- ## Task Fields @@ -261,7 +256,6 @@ The `agent` field allows per-task runner/model configuration: | `followup_reasoning_effort` | Effort for iterations > 1 | | `runner_cli` | CLI option overrides | ---- ## Queue Operations @@ -413,7 +407,6 @@ Duplicate handling (`--on-duplicate`): - `skip`: Drop duplicate tasks - `rename`: Generate fresh IDs for duplicates ---- ## Queue Locking @@ -475,7 +468,6 @@ Task operations (running actual tasks) use a shared lock mode that allows: - Individual task executions create sidecar owner files - Multiple tasks can run concurrently under the same supervisor ---- ## Auto-Archive @@ -513,7 +505,6 @@ Auto-archive automatically moves terminal tasks to done.json after a configured | Age filter | None (all terminal tasks) | Respects `auto_archive_after_days` | | Use case | Immediate cleanup | Background maintenance | ---- ## Aging @@ -598,7 +589,6 @@ Aging is calculated from different timestamps based on status: | `doing` | `started_at` | `created_at` | | `done`, `rejected` | `completed_at` | `updated_at` → `created_at` | ---- ## Example Queue Files @@ -690,7 +680,6 @@ Aging is calculated from different timestamps based on status: } ``` ---- ## Common Workflows @@ -742,7 +731,6 @@ cueloop queue repair cueloop queue archive ``` ---- ## See Also diff --git a/docs/features/scan.md b/docs/features/scan.md index 9724229e..b87e87d6 100644 --- a/docs/features/scan.md +++ b/docs/features/scan.md @@ -1,4 +1,4 @@ -# CueLoop Scan System +# Scan Status: Active Owner: Maintainers Source of truth: this document for its stated scope @@ -7,40 +7,10 @@ Parent: [Feature Documentation](README.md) ![Repository Scan](../assets/images/2026-02-07-11-32-24-scan.png) -The scan system automatically identifies opportunities, issues, and improvements in your repository by dispatching an AI agent to analyze the codebase. Unlike manual task creation, scanning explores the repository systematically to discover work you might not have explicitly recognized. +Scan dispatches a configured runner to explore the repository and enqueue structured tasks. Use it when you want discovery beyond a single `cueloop task` request. ---- +Typical uses: onboarding to a repo, pre-release checks, maintenance passes, and security or quality sweeps. Findings include evidence and priority; the agent avoids duplicating existing queue items when possible. -## Overview - -Scanning is CueLoop's **discovery mechanism** for finding work that should be done. It uses an autonomous AI agent to: - -- Explore the repository structure and code -- Identify bugs, gaps, and opportunities -- Generate properly structured tasks in the queue -- Prioritize findings based on impact and severity - -### Use Cases - -| Scenario | How Scan Helps | -|----------|----------------| -| **Onboarding to a codebase** | Quickly identify critical issues, technical debt, and missing documentation | -| **Release preparation** | Find bugs, security issues, and workflow gaps before shipping | -| **Quarterly planning** | Discover feature gaps and enhancement opportunities for roadmap planning | -| **Security audits** | Systematically identify security vulnerabilities and unsafe patterns | -| **Performance optimization** | Locate performance bottlenecks and optimization opportunities | -| **Code maintenance** | Find dead code, duplicated logic, and maintainability issues | -| **Pre-flight checks** | Validate that CI, tests, and development workflows are functioning | - -### Key Benefits - -- **Autonomous discovery**: The agent explores beyond what you explicitly ask for -- **Evidence-based**: Every finding includes concrete evidence from the codebase -- **Actionable output**: Results are structured as ready-to-work tasks in the queue -- **Prioritized**: Tasks are ranked by impact (critical → low) -- **Deduplicated**: The agent checks existing tasks to avoid duplicates - ---- ## Scan Modes @@ -137,7 +107,6 @@ cueloop scan "evaluate error handling patterns" cueloop scan "identify missing test coverage" ``` ---- ## Command Usage @@ -216,7 +185,6 @@ cueloop scan --mode maintenance --profile deep-review --runner claude \ --model opus "comprehensive security audit" ``` ---- ## Focus Prompt @@ -273,7 +241,6 @@ cueloop scan --mode maintenance "authentication system bugs" cueloop scan --mode innovation "REST API completeness" ``` ---- ## Runner Selection @@ -323,7 +290,6 @@ cueloop scan --mode maintenance --runner claude --model opus \ "design patterns and coupling issues" ``` ---- ## RepoPrompt Integration @@ -354,7 +320,6 @@ cueloop scan --repo-prompt off "quick surface scan" **CURRENTLY IMPLEMENTED BEHAVIOR**: The flag controls `repoprompt_tool_injection` which wraps the prompt with RepoPrompt requirements via `prompts::wrap_with_repoprompt_requirement()`. ---- ## Prompt Templates @@ -422,7 +387,6 @@ Custom variables can be defined in config: } ``` ---- ## Output @@ -490,7 +454,6 @@ The scan agent checks for existing tasks before adding new ones: If a duplicate is found, the agent skips adding it and reports this in the output. ---- ## Best Practices @@ -581,7 +544,6 @@ cueloop scan --mode maintenance "add null checks" - **Queue validation**: Queue is validated before and after scanning - **Force flag**: Use `--force` to bypass clean-repo check if needed ---- ## Scan vs Task Build @@ -632,7 +594,6 @@ cueloop task build-refactor --path crates/cueloop/src/auth # Result: Creates tasks for large files in auth module ``` ---- ## Advanced Usage @@ -678,7 +639,6 @@ cueloop queue export --format json --tag maintenance > audit-findings.json cueloop queue import --format json --input audit-findings.json ``` ---- ## Troubleshooting @@ -699,7 +659,6 @@ If scan fails **after** the runner finishes (for example, reloading or validatin - For **raw** safeguard dumps (secrets may be written to disk), set `CUELOOP_RAW_DUMP=1` or `CUELOOP_RAW_DUMP=true` when running `cueloop scan`. (API callers can set `ScanOptions.is_debug_mode` instead.) - For raw runner stream capture in `.cueloop/logs/debug.log`, use `cueloop run ... --debug` (scan does not accept `--debug` today). ---- ## Summary diff --git a/docs/features/security.md b/docs/features/security.md index f60b07bc..fdec29a7 100644 --- a/docs/features/security.md +++ b/docs/features/security.md @@ -9,7 +9,6 @@ Parent: [Feature Documentation](README.md) Purpose: Comprehensive guide to CueLoop's security features, including secrets redaction, safeguard dumps, debug logging, git safety, CI gate validation, plugin security, approval modes, and webhook security. ---- ## Overview @@ -23,7 +22,6 @@ Security is critical when running AI agents that have access to your codebase, e 4. **Auditability**: Clear logging and tracking of all actions 5. **Fail Safe**: Errors default to safe states ---- ## Secrets Redaction @@ -120,7 +118,6 @@ Known limitations: **Best Practice**: Always review output before sharing, even when redaction is applied. ---- ## Safeguard Dumps @@ -179,7 +176,6 @@ ls -la /tmp/cueloop/ rm -rf /tmp/cueloop/error_context_* ``` ---- ## Debug Logging @@ -245,7 +241,6 @@ log::info!("API_KEY={}", secret); // Console: API_KEY=[REDACTED] // Contains: API_KEY=actual_secret_value ``` ---- ## Runner Output Handling @@ -299,7 +294,6 @@ let err = RunnerError::NonZeroExit { println!("{}", err); // Secrets are redacted ``` ---- ## Git Safety @@ -368,7 +362,6 @@ cueloop run one --force # - You understand the risks ``` ---- ## CI Gate @@ -441,7 +434,6 @@ This ensures: 3. **Catches secrets**: Some CI gates include secret scanning 4. **Ensures tests pass**: Prevents regressions ---- ## Plugin Security @@ -507,7 +499,6 @@ Plugins are **disabled by default** and must be explicitly enabled: } ``` ---- ## Approval Modes @@ -589,7 +580,6 @@ The `safe` approval mode is **not consistently implemented** across runners and Use `auto_edits` or `yolo` for automated workflows. ---- ## Webhook Security @@ -739,7 +729,6 @@ Configure events: Use `["*"]` to subscribe to all events. ---- ## Security Checklist @@ -771,7 +760,6 @@ Use `["*"]` to subscribe to all events. - [ ] Review and update plugin trust decisions - [ ] Keep CueLoop updated: `cargo install cueloop --force` ---- ## Reporting Security Issues @@ -786,7 +774,6 @@ If you discover a security vulnerability in CueLoop: - Potential impact assessment 4. Allow reasonable time for remediation before public disclosure ---- ## Related Documentation diff --git a/docs/features/session-management.md b/docs/features/session-management.md index 259f2977..90c38541 100644 --- a/docs/features/session-management.md +++ b/docs/features/session-management.md @@ -7,7 +7,6 @@ Parent: [Feature Documentation](README.md) CueLoop's session management system provides crash recovery, explicit resume decisions, and runner-level continue support for long-running agent work. ---- ## Overview @@ -46,7 +45,6 @@ Those decisions appear across: | **Per-phase runner isolation** | Continue sessions stay phase-scoped, including deterministic Kimi session IDs. | | **Atomic persistence** | Session state is written atomically to prevent corruption. | ---- ## Session State File @@ -99,7 +97,6 @@ This file is created when a task starts and is normally cleared when the run com - `phase*_settings` are display-only; CueLoop recomputes effective settings from config + task + CLI overrides. - `git_head_commit` is advisory context, not a hard resume gate. ---- ## Run-session recovery flow @@ -150,7 +147,6 @@ If a saved session requires a decision and CueLoop cannot ask safely: This prevents headless automation from silently discarding or duplicating interrupted work. ---- ## Machine + app surfaces @@ -228,7 +224,6 @@ This preview is **read-only**: it must not clear or rewrite saved session state. CueLoopMac consumes both `resume_preview` and `resume_decision` so Run Control can show the expected action before the run starts and the actual action once the run begins. ---- ## Continue-session recovery @@ -249,7 +244,6 @@ Run-session recovery decides whether CueLoop resumes a task. Continue-session re | Claude | invalid `--resume` / invalid UUID failures | | OpenCode | session validation failures, including semantic zero-exit failures | ---- ## Kimi per-phase session IDs @@ -267,7 +261,6 @@ RQ-0001-p2-1704153600 This keeps planning / implementation / review recovery isolated from each other. ---- ## Configuration @@ -287,7 +280,6 @@ Guidance: - extended analysis: `168` - CI/headless automation: keep low and pair with an explicit `--resume` policy ---- ## Best practices @@ -312,7 +304,6 @@ cueloop run loop --resume --non-interactive cueloop run loop --non-interactive ``` ---- ## Troubleshooting @@ -333,7 +324,6 @@ Common causes: - the runner rejected the saved session id - no runner session id was available to reuse ---- ## See also diff --git a/docs/features/supervision.md b/docs/features/supervision.md index a2230747..361af385 100644 --- a/docs/features/supervision.md +++ b/docs/features/supervision.md @@ -9,7 +9,6 @@ Parent: [Feature Documentation](README.md) CueLoop's supervision system provides human-in-the-loop oversight for CI gate enforcement, git operations, and queue state management during task execution. It ensures code quality through automated checks while providing flexible recovery options when things go wrong. ---- ## Overview @@ -28,7 +27,6 @@ The supervision system orchestrates the post-execution workflow after an AI runn - **Transparency**: All supervision decisions are logged with clear reasoning - **Flexibility**: Multiple git revert modes accommodate different workflow preferences ---- ## CI Gate @@ -91,7 +89,6 @@ When the CI gate fails after exhausting retries: | `enabled` | Automatically revert uncommitted changes | | `disabled` | Leave changes in place, fail the task | ---- ## Git Operations @@ -143,7 +140,6 @@ Git LFS files are validated before commit when `--lfs-check` is enabled: cueloop run one --lfs-check ``` ---- ## Git Revert Modes @@ -202,7 +198,6 @@ Never revert changes automatically: | Task inconsistency detected | Prompt user | Auto-revert | Error only | | Non-TTY environment | Keep changes | Auto-revert | Keep changes | ---- ## Auto Commit/Push @@ -250,7 +245,6 @@ When `git_publish_mode` is `off`: - Parallel workers still run agent-owned integration (fetch/rebase/conflict-fix). - Final commit/push remains disabled; worker exits with dirty repo state for manual follow-up. ---- ## Queue Operations @@ -313,7 +307,6 @@ When the repository is clean at completion (e.g., documentation-only review): 2. Archive to done file 3. Push if ahead (for any previous commits) ---- ## Completion Checklist @@ -348,7 +341,6 @@ Override the default checklist by creating `.cueloop/prompts/phase2_handoff_chec - [ ] Security review completed ``` ---- ## Notification Integration @@ -404,7 +396,6 @@ Supervision emits webhook events for external integrations: See [Webhooks](./webhooks.md) for full configuration. ---- ## Supervision Flow @@ -500,7 +491,6 @@ CI Failure Detected └───────────┴─────────────────┘ ``` ---- ## Configuration Examples @@ -555,7 +545,6 @@ CI Failure Detected **Use Case**: Iterative development with manual git operations. ---- ## CLI Overrides @@ -578,7 +567,6 @@ cueloop run one --lfs-check cueloop run one --no-notify ``` ---- ## Troubleshooting @@ -633,7 +621,6 @@ git push -u origin HEAD # Or use AllowCreateUpstream policy in code ``` ---- ## See Also diff --git a/docs/features/task-lifecycle.md b/docs/features/task-lifecycle.md index 57894333..10e6e930 100644 --- a/docs/features/task-lifecycle.md +++ b/docs/features/task-lifecycle.md @@ -14,7 +14,6 @@ This page explains how task statuses and priorities describe work state in CueLo - [Task Operations](task-operations.md) — creation, editing, templates, batch operations, and CLI workflows. - [Queue](queue.md) — queue file operations, ordering, archive, repair, import/export, and locks. ---- ## Task Status Lifecycle @@ -76,7 +75,6 @@ if next_status.is_terminal() { } ``` ---- ## Task Priority @@ -119,7 +117,6 @@ low → medium → high → critical → low - Tasks execute in file order (top to bottom) - Priority can be used for manual filtering and UI sorting ---- ## See Also diff --git a/docs/features/task-operations.md b/docs/features/task-operations.md index 9cfce958..bb3f6a92 100644 --- a/docs/features/task-operations.md +++ b/docs/features/task-operations.md @@ -14,7 +14,6 @@ This page shows how operators create and mutate CueLoop tasks from the CLI and t - [Task Relationships](task-relationships.md) — dependency, blocking, relation, duplicate, and hierarchy semantics. - [Queue](queue.md) — queue file operations, ordering, archive, repair, import/export, and locks. ---- ## Task Creation @@ -139,7 +138,6 @@ cueloop task clone RQ-0001 --title-prefix "[Follow-up] " Creates a new task with copied fields (except ID and timestamps) and a reference in `relates_to`. ---- ## Task Editing @@ -228,7 +226,6 @@ cueloop task batch status doing RQ-0001 RQ-0002 --continue-on-error cueloop task batch edit priority low --tag-filter backlog --dry-run ``` ---- ## Task Templates @@ -299,7 +296,6 @@ cat > .cueloop/templates/security.json << 'EOF' EOF ``` ---- ## CLI Quick Reference @@ -320,7 +316,6 @@ EOF | Show parent | `cueloop task parent RQ-0002` | | Validate queue | `cueloop queue validate` | ---- ## See Also diff --git a/docs/features/task-relationships.md b/docs/features/task-relationships.md index 6e6c315e..81828f25 100644 --- a/docs/features/task-relationships.md +++ b/docs/features/task-relationships.md @@ -14,7 +14,6 @@ This page defines CueLoop task relationships: `depends_on`, `blocks`, `relates_t - [Task Operations](task-operations.md) — creation, editing, templates, batch operations, and CLI workflows. - [Queue](queue.md) — queue file operations, ordering, archive, repair, import/export, and locks. ---- ## Task Relationships @@ -148,7 +147,6 @@ cueloop queue tree --root RQ-0001 | Validation severity | Error | Error | Error | Error | Warning | | Visualization | `queue graph` | `queue graph` | None | None | `queue tree` | ---- ## Relationship Validation Summary diff --git a/docs/features/task-schema.md b/docs/features/task-schema.md index 9f90454f..57b27dba 100644 --- a/docs/features/task-schema.md +++ b/docs/features/task-schema.md @@ -14,7 +14,6 @@ This page defines the shape and validation expectations for CueLoop task objects - [Task Operations](task-operations.md) — creation, editing, templates, batch operations, and CLI workflows. - [Queue](queue.md) — queue file operations, ordering, archive, repair, import/export, and locks. ---- ## Overview @@ -56,7 +55,6 @@ Task objects live inside CueLoop queue files. This page owns the minimum task-be } ``` ---- ## Task Fields @@ -135,7 +133,6 @@ Task objects live inside CueLoop queue files. This page owns the minimum task-be - Arrays and objects are not allowed as values - Reserved analytics keys: `runner_used`, `model_used` (auto-populated on completion) ---- ## Per-Task Agent Configuration @@ -207,7 +204,6 @@ The `agent` field allows overriding global configuration for individual tasks. - Some runners may not support all CLI options (handled per `unsupported_option_policy`) - `approval_mode=safe` fails fast in non-interactive contexts (task building/updating) ---- ## Task Validation @@ -289,7 +285,6 @@ cueloop task edit status done RQ-0001 # Validates after edit } ``` ---- ## Complete Task Examples @@ -423,7 +418,6 @@ cueloop task edit status done RQ-0001 # Validates after edit } ``` ---- ## See Also diff --git a/docs/features/tasks.md b/docs/features/tasks.md index cbe12617..b28f0776 100644 --- a/docs/features/tasks.md +++ b/docs/features/tasks.md @@ -10,7 +10,6 @@ The Task System is the core unit of work in CueLoop. Tasks represent discrete pi Use this page as the task-system index. Detailed guidance lives in focused child pages so schema, lifecycle, relationship, and operator workflows can evolve without one oversized mixed-scope document. ---- ## Task Documentation Map @@ -21,7 +20,6 @@ Use this page as the task-system index. Detailed guidance lives in focused child | `depends_on`, `blocks`, `relates_to`, `duplicates`, `parent_id`, and relationship validation | [Task Relationships](task-relationships.md) | | Creating, editing, templating, cloning, importing, batching, and quick CLI workflows | [Task Operations](task-operations.md) | ---- ## Overview @@ -31,7 +29,6 @@ Tasks capture identity, state, context, relationships, and execution configurati For queue file operations and archive mechanics, see [Queue](queue.md). For the older combined reference, see [Queue and Tasks](../queue-and-tasks.md). ---- ## Task Fields diff --git a/docs/features/webhooks.md b/docs/features/webhooks.md index 215ff311..7fa800b6 100644 --- a/docs/features/webhooks.md +++ b/docs/features/webhooks.md @@ -19,13 +19,11 @@ Webhooks complement desktop notifications by providing a machine-readable, integ - **Audit Logging**: Capture task history in external systems - **Automation**: Trigger custom workflows based on task events ---- ## Quick Start: Integration Examples For copy-paste ready examples with Slack, Discord, and GitHub Actions, see **[Webhook Integration Examples](../guides/webhook-integrations.md)**. ---- ## Configuration @@ -93,7 +91,6 @@ When `enabled` is `true`, CueLoop validates `url` before delivery: HTTPS is the } ``` ---- ## Event Types @@ -146,7 +143,6 @@ The `queue_unblocked` event includes: - `current_status`: `"runnable"` - `note`: Summary counts (e.g., `"ready=2 blocked_deps=3 blocked_schedule=1"`) ---- ## Event Filtering @@ -187,7 +183,6 @@ New event types (`loop_*`, `phase_*`, `queue_unblocked`) are **not enabled by de { "events": ["loop_started", "phase_started", "phase_completed", "loop_stopped"] } ``` ---- ## Payload Format @@ -336,7 +331,6 @@ Loop events omit `task_id` and `task_title` since they are not task-specific: } ``` ---- ## Security @@ -458,7 +452,6 @@ end 4. **Use constant-time comparison** to prevent timing attacks 5. **Rotate secrets periodically** and revoke compromised secrets immediately ---- ## Delivery Semantics @@ -512,7 +505,6 @@ Webhook consumers should implement idempotency since: **Recommended approach**: Use `task_id` + `event` + `timestamp` as a unique key for deduplication. ---- ## Testing @@ -590,7 +582,6 @@ Replay safety defaults: - Replay attempts are capped per failure record (`--max-replay-attempts`). - Non-dry-run replay requires `agent.webhook.enabled=true` and a configured `agent.webhook.url`. ---- ## Integration Examples @@ -637,7 +628,6 @@ curl -X POST https://your-endpoint.com/webhook \ cueloop webhook test --url https://your-endpoint.com/webhook ``` ---- ## Reference diff --git a/docs/guides/advanced-plugins-and-automation.md b/docs/guides/advanced-plugins-and-automation.md index a9f2c139..72afdc34 100644 --- a/docs/guides/advanced-plugins-and-automation.md +++ b/docs/guides/advanced-plugins-and-automation.md @@ -7,14 +7,12 @@ Parent: [Advanced Usage Guide](advanced.md) Purpose: Deep-dive guidance for creating custom CueLoop plugins, debugging plugin execution, running CueLoop as a daemon, integrating watch mode, and wiring automation surfaces such as CI/CD and webhooks. ---- ## Table of Contents 1. [Plugin Development](#plugin-development) 2. [Automation](#automation) ---- ## Plugin Development @@ -206,7 +204,6 @@ cueloop plugin list cueloop plugin validate --id my.plugin ``` ---- ## Automation diff --git a/docs/guides/advanced-profiles-and-configuration.md b/docs/guides/advanced-profiles-and-configuration.md index 9d053fcb..110e510d 100644 --- a/docs/guides/advanced-profiles-and-configuration.md +++ b/docs/guides/advanced-profiles-and-configuration.md @@ -7,14 +7,12 @@ Parent: [Advanced Usage Guide](advanced.md) Purpose: Deep-dive guidance for composing reusable profiles, layering configuration, applying per-task agent overrides, normalizing runner CLI behavior, and injecting instruction files. ---- ## Table of Contents 1. [Custom Profiles](#custom-profiles) 2. [Advanced Configuration](#advanced-configuration) ---- ## Custom Profiles @@ -112,7 +110,6 @@ Base Config └── overrides: runner=codex, phases=3, effort=high ``` ---- ## Advanced Configuration diff --git a/docs/guides/advanced-troubleshooting.md b/docs/guides/advanced-troubleshooting.md index b50a897f..080c9b8c 100644 --- a/docs/guides/advanced-troubleshooting.md +++ b/docs/guides/advanced-troubleshooting.md @@ -195,7 +195,6 @@ cat .cueloop/logs/debug.log # Review for secrets rm -rf .cueloop/logs/ # Secure deletion ``` ---- ## Quick Reference @@ -251,4 +250,3 @@ cueloop run loop --wait-when-blocked --wait-timeout-seconds 3600 | Prompt overrides | `.cueloop/prompts/*.md` | | Plugins (project) | `.cueloop/plugins//` | | Plugins (global) | `~/.config/cueloop/plugins//` | - diff --git a/docs/guides/advanced-workflows.md b/docs/guides/advanced-workflows.md index 3ac6102d..4cd28bf4 100644 --- a/docs/guides/advanced-workflows.md +++ b/docs/guides/advanced-workflows.md @@ -7,7 +7,6 @@ Parent: [Advanced Usage Guide](advanced.md) Purpose: Deep-dive guidance for power users and teams tuning CueLoop's multi-phase execution, parallel task processing, retry/session behavior, notifications, queue cleanup, and dependency ordering. ---- ## Table of Contents @@ -15,7 +14,6 @@ Purpose: Deep-dive guidance for power users and teams tuning CueLoop's multi-pha 2. [Parallel Execution](#parallel-execution) 3. [Workflow Optimization](#workflow-optimization) ---- ## Multi-Phase Workflows @@ -121,7 +119,6 @@ CueLoop automatically retries CI failures up to 2 times. To customize this behav 2. Second CI failure → Automatic retry with stricter message 3. Third CI failure → Prompt user (revert/continue/proceed) ---- ## Parallel Execution @@ -232,7 +229,6 @@ cueloop run parallel status rm .cueloop/cache/parallel/state.json ``` ---- ## Workflow Optimization diff --git a/docs/guides/advanced.md b/docs/guides/advanced.md index 9b52db2a..6acda1d2 100644 --- a/docs/guides/advanced.md +++ b/docs/guides/advanced.md @@ -7,7 +7,6 @@ Parent: [CueLoop Documentation](../index.md) Purpose: Navigation hub for advanced CueLoop workflows, configuration patterns, integrations, automation, optimization, and troubleshooting. ---- ## Use This Guide diff --git a/docs/guides/getting-started.md b/docs/guides/getting-started.md index aad4a78d..a984594f 100644 --- a/docs/guides/getting-started.md +++ b/docs/guides/getting-started.md @@ -1,793 +1,144 @@ -# Getting Started with CueLoop -Status: Active -Owner: Maintainers -Source of truth: this document for its stated scope -Parent: [CueLoop Documentation](../index.md) +# Getting started +Status: Active +Owner: Maintainers +Source of truth: guided onboarding beyond the quick start +Parent: [Documentation index](../index.md) -This guide covers the longer onboarding path for installing CueLoop, initializing a project, creating a task, and running it through the local queue. +This guide extends [Quick start](../quick-start.md) with init details, runner choice, and a typical daily loop. For the shortest path, read quick start first, then return here for wizard behavior and habits. -## What is CueLoop? +## Prerequisites -CueLoop is a Rust CLI that runs AI agent loops against a structured JSON task queue. It can invoke Claude, Codex, OpenCode, Gemini, Cursor, Kimi, and Pi runners while keeping task state in `.cueloop/`. +- Rust toolchain (to install from crates.io: `cargo install cueloop`) +- A git repository where you want task state +- Optional: a configured AI runner CLI (Codex, Claude, Gemini, OpenCode, Cursor, Kimi, or Pi) ---- - -## Table of Contents - -1. [Installation](#1-installation) -2. [Quick Initialization](#2-quick-initialization) -3. [Your First Task](#3-your-first-task) -4. [Understanding the Workflow](#4-understanding-the-workflow) -5. [Runner Selection](#5-runner-selection) -6. [Configuration Basics](#6-configuration-basics) -7. [Daily Workflow](#7-daily-workflow) -8. [Next Steps](#8-next-steps) - ---- - -## 1. Installation - -### From crates.io (Recommended) - -The easiest way to install CueLoop is via Cargo: - -```bash -cargo install cueloop -``` - -This installs the latest published version from crates.io and provides the `cueloop` executable at `~/.cargo/bin/cueloop`. - -### From Source - -If you want the latest development version or to contribute: - -```bash -# Clone the repository -git clone https://github.com/fitchmultz/cueloop cueloop -cd cueloop - -# Build and install -make install -``` - -This installs the `cueloop` binary to `~/.local/bin/cueloop` (or a writable fallback path). - -### Verify Installation - -Check that CueLoop is properly installed: +Verify install: ```bash cueloop version ``` -You should see output like: -``` -cueloop 0.x.x -``` - -### Add to PATH - -If you installed from source, ensure `~/.local/bin` is in your PATH: - -```bash -# Add to your shell profile (.bashrc, .zshrc, etc.) -export PATH="$HOME/.local/bin:$PATH" -``` - ---- - -## 2. Quick Initialization - -CueLoop needs to be initialized in each project where you want to use it. Navigate to your project directory and run: +## Initialize a project ```bash cd your-project cueloop init ``` -`cueloop init` writes the current `"version": 2` config contract with safe defaults, no automatic publish side effects, local repo trust in `.cueloop/trust.jsonc` for current repos (gitignored by init), and generated `.cueloop/README.md` guidance. If you use the macOS app, app-launched runs stream output only; interactive approvals still require terminal-first CLI usage. - -### Interactive Wizard - -When you run `cueloop init` in a terminal (TTY), it launches an interactive wizard that will: - -1. **Choose Your AI Runner**: Select from Claude, Codex, OpenCode, Gemini, Cursor, Kimi, or Pi -2. **Select a Model**: Pick the best model for your chosen runner -3. **Configure Workflow Mode**: Choose between 1-phase (quick), 2-phase (standard), or 3-phase (full) -4. **Choose Queue Tracking**: Keep queue/done shared through git (recommended) or gitignore the full `.cueloop/` runtime directory for local-only task state -5. **Review Parallel Sync Extras**: Select additional small ignored local files workers should receive; `.env` and `.env.*` are already synced by default. Manual additions use trusted `parallel.ignored_file_allowlist`; invalid directory-tree entries such as `node_modules/*` and `dir/` are rejected. -6. **Create Your First Task** (optional): Add an initial task to get started - -### Example Walkthrough - -```bash -$ cd my-awesome-project -$ cueloop init - -✓ Initializing CueLoop in /home/user/my-awesome-project - -┌─────────────────────────────────────────┐ -│ Welcome to CueLoop! Let's get started. │ -└─────────────────────────────────────────┘ - -Choose your AI runner: - [1] Claude - General purpose, excellent reasoning (recommended) - [2] Codex - Code generation, OpenAI ecosystem - [3] OpenCode - Flexible model selection - [4] Gemini - Google ecosystem, cost efficient - [5] Cursor - Cursor IDE integration - [6] Kimi - Fast execution with session support - [7] Pi - OpenAI GPT models - -Select [1-7]: 1 - -Choose a model for Claude: - [1] sonnet (default) - Balanced speed and capability - [2] opus - Most capable, slower - [3] Other (specify ID) +`cueloop init` writes `.cueloop/config.jsonc` with safe defaults, creates or refreshes queue/done files, and (for current repos) adds gitignored `.cueloop/trust.jsonc` so local execution can work without committing machine trust. -Select [1-3]: 1 +### Interactive wizard (TTY) -Choose workflow mode: - [1] 1-phase (Quick) - Single-pass execution - [2] 2-phase (Standard) - Plan → Implement - [3] 3-phase (Full) - Plan → Implement → Review [Recommended] +When stdin is a terminal, the wizard walks through: -Select [1-3]: 3 +1. Runner selection +2. Model selection for that runner +3. Workflow mode: 1-, 2-, or 3-phase +4. Whether `.cueloop/` queue state is tracked in git or kept local-only +5. Optional extra ignored files for parallel worker sync (`.env` / `.env.*` are already included) +6. Optional first task -Would you like to create your first task? [y/N]: y -Enter task title: Add user authentication feature - -✓ Created .cueloop/config.jsonc -✓ Created .cueloop/queue.jsonc -✓ Created first task: RQ-0001 -✓ CueLoop is ready to use! -``` - -### Non-Interactive Mode - -For CI/CD or scripts, skip the wizard: +### Non-interactive / CI ```bash cueloop init --non-interactive ``` -This uses sensible defaults without prompting. +Uses defaults without prompts. Re-run with `cueloop init --force` only when you intend to overwrite existing CueLoop files. -### Force Reinitialization +See [Configuration](../configuration.md) and [Trust and precedence](../configuration/trust-and-precedence.md) for trust, git tracking, and parallel sync details. -To overwrite existing CueLoop files: +## Create and inspect tasks ```bash -cueloop init --force -``` - ---- - -## 3. Your First Task - -After initialization, you have several ways to work with tasks. - -### macOS: Open the App (SwiftUI) - -On macOS, you can use the CueLoop app for interactive queue work: - -```bash -cueloop app open -``` - -### Run Your First Task - -From the CLI, run the next task in the queue: - -```bash -# Run the next available task -cueloop run one - -# Or run a capped loop after choosing an explicit limit -cueloop run loop --max-tasks 1 -``` - -### View the Queue - -```bash -# List all tasks +cueloop task "Add regression tests for queue repair" cueloop queue list - -# Show the next task -cueloop queue next --with-title - -# Search tasks -cueloop queue search "authentication" +cueloop queue show +cueloop queue validate ``` -### Creating Tasks - -**From the CLI:** +Decompose a large goal into a previewed task tree (preview is default; `--write` persists): ```bash -# Quick task creation -cueloop task "Add password reset functionality" - -# With details -cueloop task "Refactor database layer" \ - --request "Move all database access code into a dedicated module" \ - --priority high -``` - -**From the App (macOS):** - -Open the app with `cueloop app open` and create tasks from the UI. -Use `Decompose Task...` when you want CueLoop to preview a task tree before writing multiple subtasks into the queue. - -### Example Decomposition Session - -```bash -# Preview a task tree from one broad goal cueloop task decompose "Build OAuth login with GitHub and Google" - -# Write the proposed subtree after review cueloop task decompose "Build OAuth login with GitHub and Google" --write ``` -The macOS app exposes the same preview-first workflow from the Task menu, queue toolbar, command palette, and task context menus. - -### Example Task Session - -```bash -# 1. Check what tasks exist -$ cueloop queue list -ID Status Priority Title -RQ-0001 todo medium Add user authentication feature - -# 2. Run the next task -$ cueloop run one -Starting RQ-0001: Add user authentication feature - -=== Phase 1: Planning === -Generating implementation plan... -Plan cached to .cueloop/cache/plans/RQ-0001.md - -=== Phase 2: Implementation === -Implementing plan... -Running CI gate: make agent-ci -✓ CI passed - -=== Phase 3: Review === -Reviewing changes... -✓ Task completed - -# 3. Check the result -$ cueloop queue list -ID Status Priority Title -RQ-0001 done medium Add user authentication feature -``` - ---- - -## 4. Understanding the Workflow - -CueLoop uses a structured **3-phase workflow** to ensure quality. Understanding these phases helps you choose the right mode for each task. - -### The 3 Phases - -``` -┌─────────────┐ ┌──────────────────┐ ┌──────────────────┐ -│ Phase 1 │───▶│ Phase 2 │───▶│ Phase 3 │ -│ Planning │ │ Implementation │ │ Review │ -├─────────────┤ ├──────────────────┤ ├──────────────────┤ -│ • Analyze │ │ • Execute plan │ │ • Review diff │ -│ • Research │ │ • Run CI gate │ │ • Fix issues │ -│ • Plan │ │ • Stop if CI │ │ • Final CI │ -│ (cached) │ │ fails │ │ • Complete task │ -└─────────────┘ └──────────────────┘ └──────────────────┘ -``` - -**Phase 1: Planning** -- The AI analyzes the task and creates a detailed implementation plan -- The plan is cached to `.cueloop/cache/plans/.md` -- You can review and edit this plan before implementation - -**Phase 2: Implementation** -- The AI executes the cached plan -- Changes are applied to the codebase -- When the CI gate is enabled in config, the configured command runs (for example `make agent-ci` in this repository); otherwise CueLoop skips that subprocess and prompts still remind you what verification was skipped -- If CI fails, the AI attempts to fix issues - -**Phase 3: Review** -- The AI reviews all changes against quality standards -- Any flagged issues are addressed -- When the CI gate is enabled, it runs again before completion -- Task is marked complete - -### Phase Mode Comparison - -| Mode | Phases | Best For | Speed | Quality | -|------|--------|----------|-------|---------| -| **1-Phase** | Single pass | Quick fixes, typos, simple refactors | ⚡ Fastest | Basic | -| **2-Phase** | Plan → Implement | Medium complexity, less critical code | 🚀 Fast | Good | -| **3-Phase** | Plan → Implement → Review | Complex features, production code | 🐢 Slower | ⭐ Highest | +Task model reference: [Tasks](../features/tasks.md), [Task schema](../features/task-schema.md). -### Choosing the Right Mode - -- **1-Phase**: Use for typo fixes, comment updates, simple variable renames -- **2-Phase**: Use for internal refactoring, test additions, documentation -- **3-Phase**: Use for new features, API changes, architectural decisions - -### Changing Modes - -Override phases for a single run: +## Run work ```bash -# Use 1-phase for a quick fix -cueloop run one --phases 1 - -# Or use the --quick shorthand -cueloop run one --quick +# Next runnable task +cueloop run one -# Use 3-phase for careful review +# Explicit three-phase supervision cueloop run one --phases 3 -``` - -Set default in config: -```json -{ - "agent": { - "phases": 2 - } -} +# Capped loop +cueloop run loop --max-tasks 3 ``` ---- - -## 5. Runner Selection - -CueLoop supports multiple AI runners. Choose based on your needs: - -### Runner Comparison - -| Runner | Best For | Model Options | Speed | Reasoning | -|--------|----------|---------------|-------|-----------| -| **Claude** | General purpose, complex reasoning | `sonnet` (default), `opus` | Medium | ⭐⭐⭐ Excellent | -| **Codex** | Expert coding workflows, best default path | `gpt-5.4`, `gpt-5.3-codex`, `gpt-5.3-codex-spark`, `gpt-5.3` | Fast | ⭐⭐⭐ Excellent | -| **Gemini** | Cost efficiency, speed | `gemini-3-pro-preview`, `gemini-3-flash-preview` | ⚡ Fast | ⭐⭐ Good | -| **OpenCode** | Flexible/custom endpoints | Arbitrary model IDs | Varies | Varies | -| **Cursor** | Cursor IDE users | Uses CueLoop's Node bridge with resolvable `@cursor/sdk` | Medium | ⭐⭐⭐ Excellent | -| **Kimi** | Fast execution, session support | `kimi-for-coding` | ⚡ Fast | ⭐⭐⭐ Excellent | -| **Pi** | OpenAI GPT models | `gpt-5.3` | Medium | ⭐⭐⭐ Excellent | - -### Recommended Models by Runner - -**Claude:** -- `sonnet` - Best balance of speed and capability (recommended) -- `opus` - Maximum capability for complex tasks - -**Codex:** -- `gpt-5.4` - Default and recommended for Codex in CueLoop -- `gpt-5.3-codex` - Prior Codex-tuned option -- `gpt-5.3-codex-spark` - Spark variant for coding workflows -- `gpt-5.3` - General GPT-5.3 option when you do not want a Codex-tuned model - -**Gemini:** -- `gemini-3-pro-preview` - Best quality -- `gemini-3-flash-preview` - Fastest, good for quick tasks - -**Kimi:** -- `kimi-for-coding` - Optimized for coding tasks (default) - -### Switching Runners - -Override for a single task: +Before configuring a runner, use dry-run and the [local smoke test](local-smoke-test.md) instead of a real agent pass: ```bash -# Use Claude for this run -cueloop run one --runner claude --model sonnet - -# Use Codex with high reasoning effort -cueloop run one --runner codex --model gpt-5.4 --effort high +cueloop run one --dry-run ``` -Set default in config: - -```json -{ - "agent": { - "runner": "claude", - "model": "sonnet" - } -} -``` - -### Checking Runner Availability - -Verify your runners are installed: +Readiness: ```bash cueloop doctor +cueloop queue next --with-title ``` -This checks: -- Git repository status -- Queue file validity -- Runner binary availability -- Configuration correctness - -### Installing Runners - -CueLoop requires the runner CLIs to be installed separately: - -- **Claude**: `npm install -g @anthropic-ai/claude-cli` or see Anthropic docs -- **Codex**: `npm install -g @openai/codex` -- **Gemini**: Install the Gemini CLI from Google -- **OpenCode**: Install from OpenCode -- **Cursor**: Install `@cursor/sdk` in the workspace or globally, or set `CUELOOP_CURSOR_SDK_MODULE_PATH`; CueLoop uses its Node bridge and does not require an exact SDK version match to attempt execution. See [Cursor SDK setup](../configuration/agent-and-runners.md#cursor-sdk-setup). -- **Kimi**: Install Kimi CLI -- **Pi**: Install Pi CLI - ---- - -## 6. Configuration Basics - -CueLoop uses a two-layer JSON configuration system: - -### Configuration Locations - -| Location | Purpose | Precedence | -|----------|---------|------------| -| `~/.config/cueloop/config.jsonc` | Global defaults | Lower | -| `.cueloop/config.jsonc` | Project-specific settings | Higher | -| CLI flags | One-time overrides | Highest | - -### Essential Configuration - -A minimal effective configuration: - -```json -{ - "version": 2, - "agent": { - "runner": "codex", - "model": "gpt-5.4", - "phases": 3, - "ci_gate": { - "enabled": true, - "argv": ["make", "agent-ci"] - }, - "git_publish_mode": "off" - }, - "queue": { - "file": ".cueloop/queue.jsonc", - "done_file": ".cueloop/done.jsonc" - } -} -``` - -### Key Configuration Options - -**Agent Settings:** - -```json -{ - "agent": { - "runner": "codex", // Default runner - "model": "gpt-5.4", // Default model - "phases": 3, // Default phase count (1, 2, or 3) - "iterations": 1, // Iterations per task - "reasoning_effort": "medium", // Codex: low/medium/high/xhigh - "ci_gate": { // Run make agent-ci before completion in this repo - "enabled": true, - "argv": ["make", "agent-ci"] - }, - "git_publish_mode": "off", // off / commit / commit_and_push - "git_revert_mode": "ask" // ask/enabled/disabled - } -} -``` - -**Queue Settings:** - -```json -{ - "queue": { - "file": ".cueloop/queue.jsonc", - "done_file": ".cueloop/done.jsonc", - "id_prefix": "RQ", - "id_width": 4, - "auto_archive_terminal_after_days": 7 - } -} -``` - -### Viewing Current Configuration - -```bash -# Show resolved configuration -cueloop config show - -# Show as JSON for scripting -cueloop config show --format json - -# Show file paths -cueloop config paths -``` - -### Configuration Profiles - -CueLoop always includes two built-in profiles for quick workflow switching: - -| Profile | Runner posture | Publish mode | Use Case | -|---------|----------------|--------------|----------| -| `safe` | Safer approvals | `off` | Recommended default | -| `power-user` | High-autonomy approvals | `commit_and_push` | Explicit opt-in | - -CueLoop also supports custom profiles: - -| Profile | Runner | Model | Phases | Use Case | -|---------|--------|-------|--------|----------| -| `fast-local` | Codex | gpt-5.4 | 1 | Fast local fixes | -| `deep-review` | Codex | gpt-5.4 | 3 | Deep review | - -Use a profile: - -```bash -cueloop run one --profile safe -cueloop run one --profile power-user -cueloop run one --profile fast-local -cueloop scan --profile deep-review "security audit" -``` - -Define custom profiles: - -```json -{ - "profiles": { - "fast-local": { - "runner": "codex", - "model": "gpt-5.4", - "phases": 1, - "reasoning_effort": "low" - }, - "deep-review": { - "runner": "codex", - "model": "gpt-5.4", - "phases": 3, - "reasoning_effort": "high" - } - } -} -``` - ---- +Execution details: [Phases](../features/phases.md), [Runners](../features/runners.md), [Supervision](../features/supervision.md). -## 7. Daily Workflow +## macOS app -### Typical Daily Session +The SwiftUI app shells out to the same CLI and machine contract — it is not a second workflow engine. ```bash -# 1. Start your day - check the queue -cueloop queue list - -# 2. macOS (optional): open the app UI cueloop app open - -# 3. Add tasks from code review or planning -cueloop task "Fix race condition in worker pool" -cueloop task "Update API documentation" - -# 4. Run specific high-priority tasks -cueloop run one --id RQ-0005 - -# 5. End of day - archive completed work -cueloop queue archive -``` - -### CLI Quick Reference - -| Command | Description | -|---------|-------------| -| `cueloop app open` | Open the macOS app UI | -| `cueloop run one` | Run next task | -| `cueloop run one --id RQ-0001` | Run specific task | -| `cueloop run loop --max-tasks 3` | Run a capped task loop | -| `cueloop help-all` | Show core, advanced, and experimental commands | -| `cueloop task "title"` | Create new task | -| `cueloop queue list` | List all tasks | -| `cueloop queue next` | Show next runnable task | -| `cueloop queue archive` | Move done tasks to archive | -| `cueloop doctor` | Check environment health | -| `cueloop scan "focus"` | Auto-generate tasks | - -### Managing Tasks - -**Creating good tasks:** - -```bash -# Good: Clear, actionable title -cueloop task "Add JWT authentication middleware" - -# Better: With context -cueloop task "Add JWT authentication middleware" \ - --request "Implement JWT token validation in the auth middleware. Use the existing user model." \ - --scope "src/middleware/auth.rs" \ - --priority high - -# Best: With evidence/plan -cueloop task "Add JWT authentication middleware" \ - --request "Implement JWT token validation..." \ - --evidence "Current auth uses session cookies, need JWT for API" \ - --scope "src/middleware/auth.rs,src/models/user.rs" \ - --priority high \ - --tag security \ - --tag api -``` - -**Task Dependencies:** - -```bash -# Create tasks that depend on others -cueloop task "Implement login endpoint" --tags auth -# Returns: RQ-0001 - -cueloop task "Add password reset" \ - --depends-on RQ-0001 \ - --tag auth -``` - -**Scheduling Tasks:** - -```bash -# Schedule for future execution -cueloop task "Deploy to production" \ - --scheduled-start "2026-02-15T09:00:00Z" - -# Or use relative time -cueloop task "Weekly dependency update" \ - --scheduled-start "+7d" -``` - -### Git Workflow Integration - -CueLoop works best with a clean git workflow: - -```bash -# 1. Ensure working directory is clean -git status - -# 2. Run tasks with an explicit cap (CueLoop will create commits if enabled) -cueloop run loop --max-tasks 3 - -# 3. Review changes -git log --oneline -5 - -# 4. Push when satisfied -git push -``` - -**Auto-commit configuration:** - -```json -{ - "agent": { - "git_publish_mode": "commit_and_push" - } -} -``` - -⚠️ **Warning**: Enable auto-commit only when you're comfortable with automated git operations. - ---- - -## 8. Next Steps - -Now that you're up and running, here's where to go next: - -### Learn More - -- **[CLI Reference](../cli.md)** - Complete command documentation -- **[Configuration](../configuration.md)** - All configuration options -- **[Queue and Tasks](../queue-and-tasks.md)** - Task management details -- **[Workflow](../workflow.md)** - Deep dive into the 3-phase workflow -- **[App (macOS)](../features/app.md)** - macOS SwiftUI app guide - -### Advanced Features - -For deeper multi-phase, parallel, profile, plugin, and automation patterns, see the [Advanced Usage Guide](advanced.md). - - -**Scan for Tasks:** - -Automatically discover tasks in your codebase: - -```bash -# Find maintenance issues -cueloop scan --mode maintenance "code quality gaps" - -# Find feature opportunities -cueloop scan --mode innovation "missing features" ``` -**Parallel Execution:** +See [App](../features/app.md) and [Machine contract](../machine-contract.md). -Run multiple tasks concurrently (CLI only): +## Configuration essentials -```bash -cueloop run loop --parallel 4 --max-tasks 10 -``` - -**Daemon Mode:** - -Run CueLoop continuously in the background: - -```bash -# Start daemon -cueloop daemon start +- Hub: [Configuration](../configuration.md) +- Profiles: [Profiles](../features/profiles.md) +- Prompt overrides: `.cueloop/prompts/` — [Prompts](../features/prompts.md) +- CI gate for this repo: `make agent-ci` — [CI strategy](ci-strategy.md) -# Check status -cueloop daemon status +## Daily loop -# Stop daemon -cueloop daemon stop +```mermaid +flowchart LR + A["task / scan / import"] --> B["queue list / validate"] + B --> C["run one or loop"] + C --> D["doctor / queue validate"] + D --> E["archive / done.jsonc"] ``` -**PRD to Tasks:** - -Convert Product Requirements Documents into tasks: +Typical commands: ```bash -cueloop prd create requirements.md +cueloop queue list +cueloop run one --profile safe +cueloop queue validate ``` -### Best Practices - -1. **Start small**: Begin with 1-phase tasks to get familiar -2. **Review plans**: Always check Phase 1 plans before implementation -3. **Use the app (macOS)**: Keep the queue visible while you work -4. **Archive regularly**: Keep your queue clean with `cueloop queue archive` -5. **Run doctor**: Check `cueloop doctor` if something seems off -6. **Version control**: Keep your `.cueloop/` directory in git -7. **CI gate**: Always ensure the configured CI gate passes before considering work done (`make agent-ci` in this repo) - -### Getting Help - -- **Check the docs**: Start with `docs/index.md` -- **Run doctor**: `cueloop doctor` diagnoses common issues -- **Validate queue**: `cueloop queue validate` checks for problems -- **Verbose output**: Use `--verbose` flag for more details - -### Community - -- **Issues**: Report bugs or request features -- **Contributing**: See `CONTRIBUTING.md` for guidelines -- **Security**: See `SECURITY.md` for vulnerability reporting - ---- - -## Quick Reference Card - -``` -┌────────────────────────────────────────────────────────────────┐ -│ CUELOOP QUICK REFERENCE │ -├────────────────────────────────────────────────────────────────┤ -│ INSTALL cargo install cueloop │ -│ INIT cueloop init │ -│ APP (macOS) cueloop app open │ -│ RUN cueloop run one # next task │ -│ cueloop run loop --max-tasks 1 # capped loop │ -│ TASK cueloop task "title" │ -│ LIST cueloop queue list │ -│ ARCHIVE cueloop queue archive │ -│ DOCTOR cueloop doctor │ -├────────────────────────────────────────────────────────────────┤ -│ PHASES --phases 1 (quick) --phases 2 (plan+impl) │ -│ --phases 3 (full) --quick (1-phase shorthand) │ -├────────────────────────────────────────────────────────────────┤ -│ RUNNERS --runner claude|codex|gemini|opencode|cursor|kimi|pi │ -│ --model --effort low|medium|high|xhigh │ -└────────────────────────────────────────────────────────────────┘ -``` +For parallel execution (experimental): [Parallel](../features/parallel.md). For background automation: [Daemon and watch](../features/daemon-and-watch.md). ---- +## Next steps -Happy automating! 🤖 +| Goal | Document | +| --- | --- | +| Command reference | [CLI reference](../cli.md) | +| Power-user workflows | [Advanced usage](advanced.md) | +| Evaluation / review | [Evaluator path](evaluator-path.md) | +| End-to-end fixture run | [Dogfood harness](dogfood-cueloop.md) | +| Problems | [Troubleshooting](../troubleshooting.md) | +| Contributing | [CONTRIBUTING](../../CONTRIBUTING.md) | diff --git a/docs/guides/stack-audit-2026-04.md b/docs/guides/stack-audit-2026-04.md index c6d715f1..9aaec332 100644 --- a/docs/guides/stack-audit-2026-04.md +++ b/docs/guides/stack-audit-2026-04.md @@ -3,7 +3,7 @@ Status: Active Owner: Maintainers Source of truth: current language/toolchain/dependency baseline and Rust 1.95.0 migration notes Parent: [CueLoop Documentation](../index.md) -Related: [CI and Test Strategy](ci-strategy.md), [Decisions](../decisions.md), [Archived March Stack Audit](stack-audit-2026-03.md) +Related: [CI and Test Strategy](ci-strategy.md), [Decisions](../decisions.md), [Archived March stack audit](../archive/README.md#contents) Purpose: record CueLoop's current source-build toolchain baseline, explain the Rust 1.95.0 cutover from the stale repo-local 1.94.1 override, capture the release-note compatibility checklist that drives follow-up Rust modernization tasks, and preserve the dependency/security/lint/rustdoc evidence for the current audited baseline. @@ -118,4 +118,4 @@ Because `rust-toolchain.toml` is in the Tier D routing set, expect `make agent-c - Rust `1.95.0` detailed release notes: - Rust `1.95.0` release tag: - CI and Test Strategy: [ci-strategy.md](ci-strategy.md) -- Archived March stack audit: [stack-audit-2026-03.md](stack-audit-2026-03.md) +- Archived March stack audit: [stack-audit-2026-03.md](stack-audit-2026-03.md) (see [archive](../archive/README.md)) diff --git a/docs/guides/webhook-integrations.md b/docs/guides/webhook-integrations.md index 08455a75..c3514468 100644 --- a/docs/guides/webhook-integrations.md +++ b/docs/guides/webhook-integrations.md @@ -12,7 +12,6 @@ For the complete webhook configuration reference, see [Webhooks](../features/web **Last verified:** 2026-02-15 ---- ## Overview @@ -23,7 +22,6 @@ There are two primary approaches to webhook integration: Most third-party services (Slack, Discord, GitHub Actions) require a transformation proxy because they expect specific payload structures that differ from CueLoop's standard format. ---- ## Slack Integration @@ -183,7 +181,6 @@ curl -X POST http://localhost:5000/webhook \ -d '{"event":"task_completed","timestamp":"2026-02-15T12:00:00Z","task_id":"RQ-0001","task_title":"Test task","previous_status":"doing","current_status":"done"}' ``` ---- ## Discord Integration @@ -354,7 +351,6 @@ curl -X POST http://localhost:5001/webhook \ -d '{"event":"task_completed","timestamp":"2026-02-15T12:00:00Z","task_id":"RQ-0001","task_title":"Add webhook integration docs","previous_status":"doing","current_status":"done"}' ``` ---- ## GitHub Actions Integration @@ -529,7 +525,6 @@ python github_proxy.py } ``` ---- ## Quick Reference Table @@ -539,7 +534,6 @@ python github_proxy.py | Discord | Direct or Proxy | Optional | Team notifications with rich embeds | | GitHub Actions | Proxy | Yes | CI/CD triggers, workflow automation | ---- ## Troubleshooting @@ -601,7 +595,6 @@ pip install gunicorn gunicorn -w 2 -b 0.0.0.0:5000 slack_proxy:app ``` ---- ## Further Reading diff --git a/docs/index.md b/docs/index.md index dce7e9c5..819f31e5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,101 +1,161 @@ -# CueLoop Documentation -Status: Active -Owner: Maintainers -Source of truth: this document for documentation navigation -Parent: [README](../README.md) - - -CueLoop is a Rust CLI for running AI agent loops against a structured JSON task queue. The executable is `cueloop`; the Cargo package is `cueloop`. - -## Start Here - -- [README](../README.md): product overview, first end-to-end workflow, and verification path -- [Evaluator Path](guides/evaluator-path.md): fastest reviewer-friendly path through install, queue inspection, and local verification -- [Architecture Overview](architecture.md): components, data/control flow, trust boundaries -- [Quick Start](quick-start.md): install, initialize, create first task, run it -- [Getting Started](guides/getting-started.md): longer guided onboarding path -- [Feature Guides](features/README.md): feature-specific workflows and references -- [CLI Reference](cli.md): command map + high-value workflows -- [Machine Contract](machine-contract.md): versioned app/automation JSON API -- [Project Operating Constitution](guides/project-operating-constitution.md): canonical project rules for source of truth, cutover, docs, UX, validation, and drift control -- [Decisions](decisions.md): project-level decision log -- [Configuration](configuration.md): hub for config schema, precedence, trust, runners, queues, webhooks, plugins, and profiles -- [PRD Specs](prd/cueloop-task-decompose.md): feature-level product requirements -- [Queue](features/queue.md) and [Tasks](features/tasks.md): queue semantics and task model references -- [Local Smoke Test](guides/local-smoke-test.md): deterministic install and verification path -- [CueLoop Dogfood Harness](guides/dogfood-cueloop.md): repeatable end-to-end fixture project with real three-phase runner execution -- [Agent Usage Guide](guides/agent-usage.md): machine-command workflow for already-running coding agents using CueLoop as a ledger -- [Advanced Usage Guide](guides/advanced.md): power-user workflows, profiles, plugins, automation, and optimization -- [Advanced Troubleshooting and Reference](guides/advanced-troubleshooting.md): complex recovery patterns and quick references -- [Stack Audit (2026-04)](guides/stack-audit-2026-04.md): current toolchain/dependency inventory and Rust 1.95.0 baseline review - -## Core Command Areas - -- `cueloop run`: supervised execution (`one`, `loop`, `resume`, `parallel`) -- `cueloop task`: task creation, lifecycle, relations, templates, batch ops -- `cueloop queue`: queue inspection, validation, analytics, import/export -- `cueloop scan`: repository scanning and task discovery -- `cueloop prompt`: prompt rendering/export/sync/diff -- `cueloop doctor`: readiness diagnostics -- `cueloop plugin`: plugin lifecycle -- `cueloop daemon` + `cueloop watch`: background automation -- `cueloop webhook`: test/status/replay for event delivery - -## Verification and Operations - -Use these when you want to validate a clone, understand the operational model, or prepare for a public release: - -- [README](../README.md) -- [Evaluator Path](guides/evaluator-path.md) -- [Local Smoke Test](guides/local-smoke-test.md) -- [CueLoop Dogfood Harness](guides/dogfood-cueloop.md) -- [Architecture Overview](architecture.md) -- [Public Readiness Checklist](guides/public-readiness.md) -- [Security Model](security-model.md) +# CueLoop documentation -## Reference Docs +Status: Active +Owner: Maintainers +Source of truth: navigation hub for `docs/` +Parent: [README](../README.md) -- [CLI Reference](cli.md) -- [Configuration](configuration.md) -- [CI and Test Strategy](guides/ci-strategy.md) -- [Project Operating Constitution](guides/project-operating-constitution.md) -- [Decisions](decisions.md) -- [Troubleshooting](troubleshooting.md) -- [Support Policy](support-policy.md) -- [Versioning Policy](versioning-policy.md) -- [Roadmap Archive](roadmap.md) +CueLoop is a Rust CLI (and optional macOS app) for queue-driven, auditable AI coding agent work. State lives in repo-local `.cueloop/` files so tasks can be inspected, diffed, resumed, and gated with your own commands. + +## How to read these docs + +```mermaid +flowchart TB + README["README.md
product overview"] + INDEX["docs/index.md
you are here"] + START["Start guides
install → first run"] + USE["Feature guides
queue, runners, phases"] + REF["Reference
CLI, config, schemas"] + OPS["Maintainer
CI, release, decisions"] + ARCH["Archive
historical audits"] + + README --> INDEX + INDEX --> START + INDEX --> USE + INDEX --> REF + INDEX --> OPS + START --> USE + USE --> REF + INDEX --> ARCH +``` -## Maintainer Runbooks +| If you want to… | Start here | +| --- | --- | +| Decide whether CueLoop fits your workflow | [README](../README.md) → [Evaluator path](guides/evaluator-path.md) | +| Install and run the first command | [Quick start](quick-start.md) | +| Walk through init, runners, and daily use | [Getting started](guides/getting-started.md) | +| Look up a command or flag | [CLI reference](cli.md) | +| Change behavior or runners | [Configuration](configuration.md) | +| Understand queue files and task fields | [Tasks](features/tasks.md) → [Task schema](features/task-schema.md), [Queue](features/queue.md) | +| Debug a failed run | [Troubleshooting](troubleshooting.md) | +| Contribute or change the repo | [CONTRIBUTING](../CONTRIBUTING.md) → [CI strategy](guides/ci-strategy.md) | + +## Start here + +Onboarding and verification (read in this order when evaluating the project): + +1. [README](../README.md) — problem, capabilities, and a no-runner smoke path +2. [Evaluator path](guides/evaluator-path.md) — shortest reviewer-friendly path +3. [Quick start](quick-start.md) — install, `init`, create a task, run one +4. [Local smoke test](guides/local-smoke-test.md) — scripted install/queue checks without a runner +5. [Getting started](guides/getting-started.md) — longer guided path (init wizard, runners, daily loop) + +Optional next steps: + +- [CueLoop dogfood harness](guides/dogfood-cueloop.md) — fixture repo with real three-phase execution +- [Agent usage guide](guides/agent-usage.md) — using CueLoop as a ledger from an already-running coding agent +- [Architecture overview](architecture.md) — components, trust boundaries, data flow + +## Core concepts + +| Topic | Document | +| --- | --- | +| Three-phase execution | [Phases](features/phases.md) | +| Queue files and operations | [Queue](features/queue.md) | +| Task model (index) | [Tasks](features/tasks.md) | +| Task fields and schema | [Task schema](features/task-schema.md) | +| Status lifecycle | [Task lifecycle](features/task-lifecycle.md) | +| Dependencies and relationships | [Dependencies](features/dependencies.md), [Task relationships](features/task-relationships.md) | +| Runners | [Runners](features/runners.md) | +| Parallel workers | [Parallel](features/parallel.md) | +| Supervision and CI gates | [Supervision](features/supervision.md) | + +Legacy combined references (thin hubs — prefer the links above): + +- [Queue and tasks](queue-and-tasks.md) +- [Workflow](workflow.md) + +## Feature guides + +Full index: [features/README.md](features/README.md). + +| Area | Guides | +| --- | --- | +| Execution | [Phases](features/phases.md), [Runners](features/runners.md), [Parallel](features/parallel.md), [Session management](features/session-management.md), [Supervision](features/supervision.md) | +| Automation | [Daemon and watch](features/daemon-and-watch.md), [Scan](features/scan.md), [Webhooks](features/webhooks.md), [Notifications](features/notifications.md) | +| Extensibility | [Plugins](features/plugins.md), [Plugin development](plugin-development.md), [Prompts](features/prompts.md), [Profiles](features/profiles.md) | +| Data | [Import/export](features/import-export.md), [Migrations](features/migrations.md) | +| macOS app | [App](features/app.md), [Machine contract](machine-contract.md) | +| Security | [Security features](features/security.md), [Security model](security-model.md), [SECURITY.md](../SECURITY.md) | + +## Reference + +| Document | Contents | +| --- | --- | +| [CLI reference](cli.md) | Commands, flags, common workflows | +| [Configuration](configuration.md) | Config hub and deep dives under `configuration/` | +| [Machine contract](machine-contract.md) | Versioned JSON API for app and automation | +| [Environment](environment.md) | Environment variables | +| [Error handling](error-handling.md) | Failure patterns | +| [Schemas](../schemas/) | Generated JSON schemas (`make generate`) | +| [Versioning policy](versioning-policy.md) | Semver and breaking-change expectations | +| [Support policy](support-policy.md) | Support expectations | + +Configuration deep dives: + +- [Agent and runners](configuration/agent-and-runners.md) +- [Queue and parallel](configuration/queue-and-parallel.md) +- [Trust and precedence](configuration/trust-and-precedence.md) +- [Notifications and webhooks](configuration/notifications-and-webhooks.md) +- [Plugins and profiles](configuration/plugins-and-profiles.md) +- [Migration notes](configuration/migration-notes.md) + +## Operations and quality + +| Document | Contents | +| --- | --- | +| [CI and test strategy](guides/ci-strategy.md) | `make agent-ci`, tiers, routing | +| [Troubleshooting](troubleshooting.md) | Common failures | +| [Advanced usage](guides/advanced.md) | Hub for power-user guides | +| [Public readiness](guides/public-readiness.md) | Pre-release checklist | +| [Project operating constitution](guides/project-operating-constitution.md) | Maintainer rules (compact) | + +Default validation from the repo root (GNU Make ≥ 4): -- [Release Runbook](guides/release-runbook.md) -- [Full Release Guide](releasing.md) +```bash +make agent-ci +``` -## Runtime Paths (Defaults) +Release-shaped gate: `make release-gate`. Routing uses only the **current uncommitted** diff; see [CI strategy](guides/ci-strategy.md#agent-ci-classifier-path-list) for debugging (`scripts/agent-ci-surface.sh --target`). -- Queue: `.cueloop/queue.jsonc` -- Done archive: `.cueloop/done.jsonc` -- Project config: `.cueloop/config.jsonc` -- Prompt overrides: `.cueloop/prompts/` -- Runtime migration: use `cueloop migrate runtime-dir --check` before applying supported old-state migrations. +## Maintainer -## Validation and CI +| Document | Contents | +| --- | --- | +| [Decisions](decisions.md) | Decision log | +| [Roadmap archive](roadmap.md) | Historical follow-ups (not active roadmap) | +| [Release runbook](guides/release-runbook.md) | Release steps | +| [Releasing](releasing.md) | Full release guide | +| [Stack audit (2026-04)](guides/stack-audit-2026-04.md) | Toolchain baseline | +| [Releasing / security](releasing.md), [SECURITY.md](../SECURITY.md) | Ship and vulnerability reporting | -> GNU Make >= 4 is required for project targets. On macOS, install with `brew install make` and use `gmake` unless your PATH already exposes GNU Make as `make`. +Product requirements: -Use [`docs/guides/ci-strategy.md`](guides/ci-strategy.md) as the canonical validation guide. +- [Task decompose PRD](prd/cueloop-task-decompose.md) -Routine branch gate: +Agent-only repo guidance: [AGENTS.md](../AGENTS.md) (not duplicated here). -```bash -make agent-ci -``` +## Runtime paths (defaults) -Final ship/release gate: +| Path | Role | +| --- | --- | +| `.cueloop/queue.jsonc` | Active tasks | +| `.cueloop/done.jsonc` | Completed / rejected archive | +| `.cueloop/config.jsonc` | Project configuration | +| `.cueloop/prompts/*.md` | Prompt overrides (defaults embedded in CLI) | -```bash -make release-gate -``` +Before migrating old runtime layouts: `cueloop migrate runtime-dir --check`. -Lower-level targets such as `ci-docs`, `ci-fast`, `ci`, and `macos-ci` still exist, but most contributors should treat them as internal tiers behind `make agent-ci` rather than commands to choose among day to day. +## Archive -Routing uses only the **current uncommitted** working tree (including untracked paths); commits already on the branch do not change the tier. To debug routing, run `scripts/agent-ci-surface.sh --target` and `--reason` from the repo root. Changes to `scripts/agent-ci-surface.sh` or path allowlists in `scripts/lib/release_policy.sh` should stay aligned with contract coverage in [`crates/cueloop/tests/agent_ci_surface_contract_test.rs`](../crates/cueloop/tests/agent_ci_surface_contract_test.rs) (see [`docs/guides/ci-strategy.md`](guides/ci-strategy.md)). +Historical audits and superseded notes: [archive/README.md](archive/README.md). diff --git a/docs/prd/cueloop-task-decompose.md b/docs/prd/cueloop-task-decompose.md index c9b9063f..f2bc9c12 100644 --- a/docs/prd/cueloop-task-decompose.md +++ b/docs/prd/cueloop-task-decompose.md @@ -147,33 +147,41 @@ so that it does not mutate queue state unless I explicitly request it. - Queue mutation still requires `--write` explicitly. - Validation failures produce deterministic, human-readable output. -## Functional Requirements - -1. CueLoop SHALL add a new `cueloop task decompose` subcommand under the existing `task` command group. -2. CueLoop SHALL accept a freeform request, a `--from-file ` plan document, or an existing task ID as the decomposition source. -3. CueLoop SHALL support a preview-first workflow and SHALL NOT mutate queue state unless `--write` is provided. -4. CueLoop SHALL generate durable queue tasks rather than ephemeral planner-only output. -5. CueLoop SHALL represent task hierarchy using the existing `parent_id` field. -6. CueLoop SHALL reuse existing queue ID allocation so generated task IDs remain unique across queue and done archives. -7. CueLoop SHALL create valid `created_at` and `updated_at` timestamps for all newly written tasks. -8. CueLoop SHALL preserve the decomposed source task by default when decomposing an existing active task. -9. CueLoop SHALL support configurable recursion depth limits. -10. CueLoop SHALL support configurable per-node fanout limits. -11. CueLoop SHALL enforce a total generated node safety limit before writing queue state. -12. CueLoop SHALL treat hierarchy and execution ordering as separate concepts. -13. CueLoop SHALL reuse queue locking and undo snapshot behavior for write operations. -14. CueLoop SHALL validate queue state before and after decomposition writes. -15. CueLoop SHALL include deterministic human-readable preview output that can be inspected before write. -16. CueLoop SHALL integrate with existing hierarchy navigation commands such as `cueloop queue tree`, `cueloop task children`, and `cueloop task parent`. -17. CueLoop SHALL support runner, model, reasoning-effort, RepoPrompt, and runner CLI override flags consistent with other runner-backed task creation flows. -18. CueLoop SHALL use a dedicated decomposition prompt/template rather than overloading task-builder or scan prompts. -19. CueLoop SHALL fail safely when planner output is malformed, incomplete, or inconsistent with queue rules. -20. CueLoop SHALL support `--attach-to ` for freeform request and plan-file decomposition under an existing active parent task. -21. CueLoop SHALL support `--child-policy fail|append|replace` for effective parents with existing child trees. -22. CueLoop SHALL support optional sibling dependency inference behind `--with-dependencies`. -23. CueLoop SHALL emit stable versioned JSON output when `--format json` is requested. -24. CueLoop SHALL persist generated decomposition grouping nodes as `kind: group` and generated leaves as `kind: work_item`. -25. CueLoop SHALL report root/group and first actionable leaf metadata in preview and write outputs. +## Functional requirements + +### Command and sources + +- Add `cueloop task decompose` under the existing `task` command group. +- Accept a freeform request, `--from-file `, or an existing task ID as the decomposition source. +- Use a dedicated decomposition prompt/template (not task-builder or scan prompts). + +### Preview and writes + +- Default to preview; do not mutate `.cueloop/queue.jsonc` unless `--write` is set. +- Emit deterministic human-readable preview output; support `--format json` with stable versioned payloads. +- On write: acquire the queue lock, create an undo snapshot, validate before and after, and fail without partial writes on validation errors. + +### Generated tasks + +- Create durable queue tasks (not ephemeral planner-only output). +- Represent hierarchy with `parent_id`; persist grouping nodes as `kind: group` and leaves as `kind: work_item`. +- Allocate IDs via existing queue ID rules (unique across queue and done archives). +- Set valid `created_at` and `updated_at` on every new task. +- Preserve the source task by default when decomposing an existing active task. +- Report root/group node and first actionable leaf in preview and write output. + +### Limits and safety + +- Support configurable recursion depth, per-node fanout, and a total node cap before write. +- Treat hierarchy and execution ordering separately; optional sibling `depends_on` only with `--with-dependencies`. +- Fail safely on malformed or inconsistent planner output. +- Never reuse existing task IDs; reject parent cycles. + +### Flags and integration + +- Support runner, model, reasoning-effort, RepoPrompt, and runner CLI overrides consistent with other runner-backed task flows. +- Support `--attach-to `, `--child-policy fail|append|replace`, and `--with-dependencies`. +- Work with existing hierarchy commands: `cueloop queue tree`, `cueloop task children`, `cueloop task parent`. ## User Experience @@ -298,45 +306,30 @@ Planner guidance should emphasize: ## Product Decisions -### Preview Default - -Preview SHALL be the hard default in all environments. +### Preview default -- `cueloop task decompose ` performs a preview only. -- Queue mutation requires explicit `--write`. -- There is no TTY-only “safety behavior” split for preview vs write. -- This keeps the command predictable, scriptable, and safe. +Preview is the default in all environments: -Rationale: +- `cueloop task decompose ` previews only; `--write` is required to mutate the queue. +- No TTY-only split between preview and write (predictable for scripts and the macOS app bridge). -- Decomposition is a high-blast-radius planning command that can create many tasks at once. -- Hidden environment-dependent behavior is a bad fit for automation and a bad fit for user trust. -- Users should never have to remember whether they were in a terminal, CI shell, or app bridge to know whether queue state changed. +Decomposition can create many tasks at once; environment-dependent write behavior would be hard to trust in automation. -### Existing Parent with Existing Children +### Existing parent with children -Default behavior when decomposing an existing task that already has children SHALL be to refuse write unless the caller explicitly chooses `--child-policy append` or `--child-policy replace`. +When decomposing a task that already has children, refuse write unless `--child-policy append` or `--child-policy replace` is set. Preview still runs and explains the conflict. -Preview still succeeds and shows the conflict or selected policy. - -Rationale: +- `fail` — safest default +- `append` — non-destructive extension +- `replace` — only with reference checks and undo coverage -- `fail` remains the safest default. -- `append` gives users an explicit non-destructive extension path. -- `replace` is acceptable only with strict reference checks and undo coverage. - -### Dependency Inference Scope - -Dependency inference SHALL be optional and limited to siblings within the same generated parent group. - -Rationale: +### Dependency inference scope -- Sibling-only inference captures the most useful ordering constraints without exposing the planner to arbitrary queue-wide references. -- Restricting inference scope keeps validation and debugging tractable. +`--with-dependencies` is optional and limited to siblings under the same generated parent. This keeps validation tractable and avoids planner references to arbitrary queue IDs. -### Parent Annotation Strategy +### Parent annotation (v1) -Decomposed parent tasks SHALL receive a human-readable note in v1. +Decomposed parent tasks get a human-readable note in v1. Rationale: diff --git a/docs/queue-and-tasks.md b/docs/queue-and-tasks.md index 37493e84..330d7028 100644 --- a/docs/queue-and-tasks.md +++ b/docs/queue-and-tasks.md @@ -1,471 +1,32 @@ -# Queue and Tasks -Status: Active -Owner: Maintainers -Source of truth: this document for its stated scope -Parent: [CueLoop Documentation](index.md) +# Queue and tasks (legacy hub) +Status: Active +Owner: Maintainers +Source of truth: navigation only — detailed content lives in linked guides +Parent: [Documentation index](index.md) -![Queue Lifecycle](assets/images/2026-02-07-queue-lifecycle.png) +This page exists for older links and tests that reference `docs/queue-and-tasks.md`. Use the focused guides below instead of treating this file as a full reference. -Purpose: Define the queue file format, task fields, and status lifecycle based on `schemas/queue.schema.json`. +## Where to look -## Queue File -The queue file (`.cueloop/queue.jsonc`) is the source of truth for active work. Completed tasks are moved to `.cueloop/done.jsonc`, which must contain only `done` or `rejected` tasks. +| Topic | Document | +| --- | --- | +| Queue file, validation, operations | [Queue](features/queue.md) | +| Task index and operations | [Tasks](features/tasks.md) | +| Field definitions and schema | [Task schema](features/task-schema.md) | +| Status transitions | [Task lifecycle](features/task-lifecycle.md) | +| `depends_on`, `blocks`, graph | [Dependencies](features/dependencies.md), [Task relationships](features/task-relationships.md) | +| Machine-readable schema | [schemas/queue.schema.json](../schemas/queue.schema.json) | -Minimum queue structure: -```json -{ - "version": 1, - "tasks": [] -} -``` - -## Task Fields -Each task is an object with required and optional fields. - -Required: -- `id` (string) -- `title` (string) -- `created_at` (string, RFC3339 UTC) -- `updated_at` (string, RFC3339 UTC) - -Common optional fields: -- `tags` (list of strings, defaults to empty). -- `scope` (list of strings, defaults to empty): Scope is a starting point, not a restriction. Use it for relevant paths/commands and expand as needed. -- `evidence` (list of strings, defaults to empty). -- `plan` (list of strings, defaults to empty). -- `notes` (list of strings, defaults to empty). -- `status`: `draft`, `todo`, `doing`, `done`, `rejected` (default: `todo`). Lifecycle only; it does not say whether the task is executable. -- `kind`: `work_item` or `group` (default: `work_item`). `work_item` tasks are executable atomic work. `group` tasks are non-runnable decomposition/organization nodes. CueLoop omits `kind` when saving default `work_item` tasks; write `kind: "group"` only when the task must be non-executable. -- `priority`: `critical`, `high`, `medium`, `low` (default: `medium`). -- `request`: original human request (string or null). -- `completed_at`: RFC3339 UTC timestamp (required if status is `done` or `rejected`, otherwise optional). -- `started_at`: RFC3339 UTC timestamp when work started (optional). -- `estimated_minutes`: Estimated time to complete in minutes (optional, for planning). -- `actual_minutes`: Actual time spent in minutes (optional, for tracking). -- `agent`: per-task runner override (see below). -- `depends_on` (list of task IDs, defaults to empty). -- `blocks` (list of task IDs, defaults to empty): Tasks that this task blocks. Semantically different from `depends_on`: blocks is "I prevent X" vs depends_on "I need X". -- `relates_to` (list of task IDs, defaults to empty): Tasks that this task relates to (loose coupling, no execution constraint). -- `duplicates` (string or null): Task ID that this task duplicates. -- `custom_fields` (map of strings, defaults to empty). - - **Note**: The queue loader accepts string/number/boolean values and coerces them to strings (in memory, and on subsequent saves). When manually editing `.cueloop/queue.jsonc`, values should still be quoted strings for consistency. - - **Reserved analytics keys**: CueLoop automatically writes the following keys to completed tasks: - - `runner_used`: The runner actually used for execution (e.g., `codex`, `claude`, `opencode`). - - `model_used`: The model actually used for execution (e.g., `gpt-5.3-codex`, `sonnet`). - - These fields are observational (what actually ran) and should not be confused with `agent.runner`/`agent.model` which express intent/override. - -Per-task agent overrides: -- `agent.runner`: Built-in runner ID (`codex`, `opencode`, `gemini`, `claude`, `cursor`, `kimi`, or `pi`) or plugin runner ID. -- `agent.model`: model id string. -- `agent.model_effort`: `default`, `low`, `medium`, `high`, `xhigh` (Codex and Pi only). -- `agent.phases`: number of phases for this task (`1`, `2`, or `3`). -- `agent.iterations`: number of iterations for this task (default: 1). -- `agent.followup_reasoning_effort`: reasoning effort for iterations after the first (Codex and Pi only). -- `agent.phase_overrides.phase1|phase2|phase3.runner`: per-phase runner override. -- `agent.phase_overrides.phase1|phase2|phase3.model`: per-phase model override. -- `agent.phase_overrides.phase1|phase2|phase3.reasoning_effort`: per-phase reasoning effort override (Codex and Pi only). - -Notes: -- `agent.model_effort: default` (or omitting the field) uses the configured `agent.reasoning_effort`. -- `agent.followup_reasoning_effort` is ignored for runners without reasoning-effort support. -- Phase resolution precedence is: CLI phase overrides > task phase overrides > config phase overrides > CLI global overrides > task global overrides > config defaults. -- Breaking change: `agent.reasoning_effort` in task entries is replaced by `agent.model_effort`. - -## Example Task -```json -{ - "id": "RQ-0007", - "title": "Add CI validation for queue format", - "status": "doing", - "priority": "high", - "created_at": "2026-01-25T03:45:00Z", - "updated_at": "2026-01-25T03:45:00Z", - "tags": ["cli", "queue"], - "scope": ["schemas/queue.schema.json", "crates/cueloop/src/cli/queue.rs"], - "plan": ["Add schema validation to queue validate."], - "evidence": ["make agent-ci"], - "depends_on": [], - "custom_fields": { - "owner": "platform" - }, - "agent": { - "runner": "codex", - "model": "gpt-5.3-codex", - "model_effort": "high", - "phases": 2, - "iterations": 2, - "followup_reasoning_effort": "low", - "phase_overrides": { - "phase2": { - "runner": "kimi", - "model": "kimi-code/kimi-for-coding" - } - } - } -} -``` +## Quick reference -## Lifecycle Notes -- Executable `work_item` tasks run in the file order from `.cueloop/queue.jsonc`. -- `kind: "group"` tasks remain visible in reads, lists, tree, graph, search, and app surfaces, but are skipped by `cueloop queue next`, `run one`, `run loop`, parallel workers, and machine runnability selection by default. -- Existing tasks without `kind` load as `work_item`; CueLoop omits the default `work_item` field on save so normal task rewrites stay compatible with older strict readers. Explicit `kind: "group"` requires a CueLoop build that supports task kinds. -- Completed tasks are removed from `.cueloop/queue.jsonc` and appended to `.cueloop/done.jsonc`. -- Dependencies: A task is blocked until all IDs in its `depends_on` list have status `done` or `rejected`. -- Draft tasks (`status: draft`) are skipped by `run one` and `run loop` unless `--include-draft` is set. -- Decomposed leaves written as `draft` are intentionally skipped until activated. Use `cueloop task ready ` to promote a reviewed leaf to runnable `todo` work; `cueloop task decompose --write` prints the exact first-leaf command when all generated work remains draft. -- `cueloop queue validate` and `cueloop queue explain` treat a normal all-draft decomposition as waiting for activation, not queue corruption: `No runnable tasks because all tasks are draft. Promote a leaf task to todo.` -- To avoid an all-draft decomposition by intent, write parent/group nodes as draft while making generated leaf work runnable with `cueloop task decompose --write --parent-status draft --leaf-status todo ""`. - -## Discovery Follow-Ups - -Exploratory, audit, scan, and investigation tasks should grow the queue when they find independent work. CueLoop uses `followups@v1` proposal files so agents can describe follow-up tasks without hand-editing queue JSON. - -Default proposal path: - -```text -.cueloop/cache/followups/.json -``` - -Proposal shape: - -```json -{ - "version": 1, - "source_task_id": "RQ-0135", - "tasks": [ - { - "key": "docs-hierarchy", - "title": "Rework oversized docs into a feature hierarchy", - "description": "Split oversized documentation into navigable feature pages with clear ownership.", - "priority": "high", - "tags": ["docs"], - "scope": ["docs/"], - "evidence": ["Audit found oversized docs with mixed feature coverage."], - "plan": ["Identify target hierarchy.", "Move content.", "Update links."], - "depends_on_keys": [], - "independence_rationale": "This is separate remediation work discovered by the audit." - } - ] -} -``` +- Active work: `.cueloop/queue.jsonc` +- Archive: `.cueloop/done.jsonc` (terminal statuses only) +- Default executable tasks: `kind: work_item` (omit `kind` on save) +- Non-runnable grouping nodes: `kind: group` -Apply a proposal: +Validate after edits: ```bash -cueloop task followups apply --task RQ-0135 -cueloop task followups apply --task RQ-0135 --dry-run --format json +cueloop queue validate ``` - -Apply allocates real task IDs, maps `depends_on_keys`, inherits `request` from the source task, adds `relates_to: [""]`, timestamps the tasks, validates the queue, creates undo for CLI applies, and removes the proposal after a successful non-dry-run apply. The canonical `version` value is numeric `1`; `followups@v1` names the proposal contract, not the JSON `version` value. Proposal `key` values are local slugs, and `depends_on_keys` can reference only keys declared in the same proposal file. - -Follow-ups are for independent work or queue-shaping tasks. They must not replace completing the active task's current scope. Reports remain opt-in: create a report only when the user explicitly asked for one or when the report is the deliverable. Normal run finalization treats an invalid proposal as repairable follow-up metadata: it logs a warning, leaves the proposal file in place, and continues finalization instead of failing the whole run loop. - -## Atomic Task Insertion for Agents and Scripts - -When agents or scripts already know the full task content, prefer `cueloop task insert` over `cueloop queue next-id` plus manual JSON editing. - -```bash -cueloop task insert --input /tmp/task-insert.json -cueloop task insert --dry-run --format json --input /tmp/task-insert.json -``` - -Minimal request shape: - -```json -{ - "version": 1, - "tasks": [ - { - "key": "queue-safety", - "title": "Make agent task insertion atomic", - "status": "todo", - "priority": "medium", - "tags": ["scan", "queue"], - "scope": ["crates/cueloop/src/queue/operations/insert.rs"], - "evidence": ["path: ..."], - "plan": ["Insert via locked queue path.", "Run cueloop queue validate."], - "request": "scan: queue safety" - } - ] -} -``` - -Rules: -- Omit durable `id`, `created_at`, and `updated_at` fields; CueLoop assigns/stamps them while holding the queue lock. -- Use local `key` values and `depends_on_keys` when multiple new tasks depend on each other. -- `cueloop queue next-id` remains available for human/manual recovery, but it is preview-only and does **not** reserve IDs. - -## Dependency Validation - -CueLoop validates task dependencies on queue operations to ensure correctness and prevent issues: - -### Hard Errors (blocking) -These validation failures prevent queue operations and must be fixed: - -- **Self-dependency**: A task cannot depend on itself. -- **Missing dependency**: Referenced task ID must exist in `.cueloop/queue.jsonc` or `.cueloop/done.jsonc`. -- **Circular dependency**: Dependency graph must be acyclic (DAG). -- **Invalid terminal status**: `.cueloop/done.jsonc` must only contain tasks with `done` or `rejected` status. - -### Relationship Validation - -CueLoop also validates task relationships (`blocks`, `relates_to`, `duplicates`) to ensure correctness: - -**Hard Errors (blocking):** -- **Self-reference**: A task cannot block, relate to, or duplicate itself. -- **Missing target**: Referenced task ID must exist in `.cueloop/queue.jsonc` or `.cueloop/done.jsonc`. -- **Circular blocking**: Blocking relationships must form a DAG (no cycles). - -**Warnings (non-blocking):** -- **Duplicate of done/rejected task**: Task duplicates a completed or rejected task. - -Relationships are distinct from dependencies: -- `depends_on`: "I need X" (execution constraint - task waits for dependencies) -- `blocks`: "I prevent X" (execution constraint - blocked tasks wait for this task) -- `relates_to`: Loose coupling (no execution constraint, just semantic association) -- `duplicates`: Marks redundancy (no execution constraint, informational only) - -## Hierarchy (parent_id) - -Tasks can form a parent/child hierarchy using the `parent_id` field. This is useful for: -- Decomposing large tasks (epics) into subtasks -- Tracking task splits and their origins -- Organizing work hierarchically without affecting execution order - -### How it Works - -- `parent_id`: Optional field containing the ID of the parent task -- A task can have at most one parent -- A parent can have multiple children -- Cycles are not allowed (A -> B -> A) -- Unlike `depends_on`, parent/child relationships do not affect execution order -- `parent_id` is hierarchy only. Use `kind: "group"` when a parent should be non-executable; a parent can still be a `work_item` when it represents atomic work. - -### Example - -```json -{ - "id": "RQ-0001", - "title": "Implement feature X", - "status": "todo", - "kind": "group" -}, -{ - "id": "RQ-0002", - "title": "Implement feature X - Part 1", - "status": "todo", - "parent_id": "RQ-0001" -}, -{ - "id": "RQ-0003", - "title": "Implement feature X - Part 2", - "status": "todo", - "parent_id": "RQ-0001" -} -``` - -### CLI Navigation Commands - -CueLoop provides commands to navigate the hierarchy: - -```bash -# List child tasks -cueloop task children RQ-0001 - -# List children recursively (tree view) -cueloop task children RQ-0001 --recursive - -# Include done archive in search -cueloop task children RQ-0001 --include-done - -# Show parent task -cueloop task parent RQ-0002 - -# Render full hierarchy tree -cueloop queue tree - -# Render tree starting from specific root -cueloop queue tree --root RQ-0001 - -# Include done tasks in tree -cueloop queue tree --include-done -``` - -### Hierarchy vs Dependencies - -It's important to understand the difference: - -| Feature | `parent_id` | `depends_on` | -|---------|-------------|--------------| -| Purpose | Structural organization | Execution ordering | -| Affects task order | No | Yes | -| Visualized with | `cueloop queue tree` | `cueloop queue graph` | -| Validation | Warnings for cycles/missing parents | Hard errors for cycles/missing deps | - -Use `kind` for actionability: `kind: "group"` prevents default execution selection, while `kind: "work_item"` can run when lifecycle/dependencies/schedule allow it. - -### Parent ID Validation - -CueLoop validates `parent_id` references and reports issues as warnings: - -**Warnings (non-blocking):** -- **Missing parent**: Task references a parent that doesn't exist -- **Self-parent**: Task references itself as its own parent -- **Circular parent chain**: A cycle exists in the parent hierarchy (A -> B -> A) - -These warnings do not prevent queue operations but should be reviewed and fixed. - -### Warnings (non-blocking) -These issues are reported but do not prevent queue operations: - -- **Dependency on rejected task**: Task depends on a rejected task that will never complete. The dependency will never be satisfied. -- **Deep dependency chain**: Dependency chain exceeds `queue.max_dependency_depth` (default: 10). This may indicate overly complex dependencies. -- **Blocked execution path**: All dependency paths from a runnable active task lead to incomplete or rejected tasks. The task cannot make progress until blocking dependencies are resolved. Draft-only decomposition trees are summarized as activation guidance instead of one warning per draft task. -- **Duplicate of done/rejected task**: Task marked as duplicate of a completed or rejected task. Consider if the duplicate is still needed. - -### Configuration - -Set `queue.max_dependency_depth` in `.cueloop/config.jsonc` to adjust the depth warning threshold: - -```json -{ - "queue": { - "max_dependency_depth": 15 - } -} -``` - -Validation warnings are logged during queue operations. Review them with `cueloop queue validate` or by checking the queue after operations. - -## Task ID Validation - -CueLoop enforces unique task IDs across **both** `.cueloop/queue.jsonc` **AND** `.cueloop/done.jsonc`. Duplicate IDs will cause validation errors and block most queue operations. - -> **Important:** Completed task IDs in `.cueloop/done.jsonc` remain "claimed" and are included in uniqueness checks. Even though tasks are archived, their IDs cannot be reused for new tasks to prevent collisions with historical references. - -### Duplicate Task ID Errors - -**Error:** `Duplicate task ID detected across queue and done: RQ-XXXX` - -This error occurs when the same task ID exists in both the active queue and the done archive. This typically happens when: - -1. A new task was added to the queue without incrementing the ID properly -2. A task was manually copied/edited and the ID wasn't updated -3. Task files were edited directly and IDs became misaligned - -### Fixing ID Collisions - -**Important:** Do not delete tasks to resolve collisions. Instead, update the ID of the task in `.cueloop/queue.jsonc` to the next available unique ID. - -**Steps to fix:** - -1. Identify the colliding ID (e.g., `RQ-0452` exists in both files) -2. Check if the tasks are different (different titles, descriptions, or content) -3. Find the next available ID using: - ```bash - cueloop queue next-id - ``` -4. Update the task ID in `.cueloop/queue.jsonc` to the next available ID -5. Re-run validation to confirm: - ```bash - cueloop queue validate - ``` - -**Example:** - -If `RQ-0452` exists in both `.cueloop/done.jsonc` (completed task about "Fix Kimi runner") and `.cueloop/queue.jsonc` (new task about "Add feature X"), the fix is to change the queue task's ID to `RQ-0453` (or whatever `next-id` returns). - -### Prevention - -- Use `cueloop task` commands to create tasks; prefer `cueloop task insert` for agent/script queue shaping because it allocates IDs under the queue lock. -- Use `cueloop queue next-id` only for manual recovery or one-off JSON surgery; it previews IDs but does **not** reserve them. -- Always run `cueloop queue validate` after manual edits to catch issues early - -## Dependency Visualization - -![Dependency Graph](assets/images/2026-02-07-dependency-graph.png) - -CueLoop provides multiple ways to visualize task dependencies: - -### CLI Graph Command - -The `cueloop queue graph` command displays dependency relationships: - -```bash -# ASCII tree view of dependencies -cueloop queue graph --task RQ-0001 - -# Graphviz DOT format for external rendering -cueloop queue graph --format dot > deps.dot -dot -Tpng deps.dot -o deps.png - -# Show what tasks are blocked by a specific task -cueloop queue graph --task RQ-0001 --reverse - -# Highlight critical path (longest dependency chain) -cueloop queue graph --critical -``` - -### macOS App - -On macOS, you can explore dependencies interactively in the CueLoop app: - -```bash -cueloop app open -``` - -### Critical Path - -The critical path is the longest dependency chain in the graph. Tasks on the critical path are highlighted with `*` in tree/list output. Completing critical path tasks unblocks the most downstream work. -- `cueloop task` inserts new tasks near the top of the queue: - - Default: insert at position 0 (top). - - If the first task is already `doing`, insert at position 1 (immediately below the in-progress task). - -## Import and Export - -CueLoop supports importing and exporting tasks for bulk operations, cross-repo migration, and integration with external tools. - -### Export - -Export tasks to CSV, TSV, JSON, Markdown, or GitHub issue format: - -```bash -# Export all tasks to CSV (default) -cueloop queue export - -# Export to JSON for scripting -cueloop queue export --format json --output tasks.json - -# Export tasks with specific tags to TSV -cueloop queue export --format tsv --tag rust --tag cli -``` - -### Import - -Import tasks from CSV, TSV, or JSON into the active queue. This enables bulk backlog seeding and cross-repo task migration without hand-editing JSON. - -```bash -# Import from JSON file -cueloop queue import --format json --input tasks.json - -# Import from CSV with dry-run to preview changes -cueloop queue import --format csv --input tasks.csv --dry-run - -# Pipe export to import (round-trip test) -cueloop queue export --format json | cueloop queue import --format json --dry-run -``` - -**Normalization**: During import, CueLoop automatically: -- Trims all fields and drops empty list items -- Backfills missing `created_at`/`updated_at` timestamps -- Sets `completed_at` for tasks with `done`/`rejected` status -- Generates IDs for tasks without them -- Validates the final queue state before writing - -**Duplicate handling**: Use `--on-duplicate` to control behavior when imported task IDs already exist: -- `fail` (default): error on duplicates -- `skip`: drop duplicate tasks -- `rename`: generate fresh IDs for duplicates - -See `docs/cli.md` for full import documentation. diff --git a/docs/roadmap.md b/docs/roadmap.md index a6226a23..a0dad003 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -5,7 +5,7 @@ Source of truth: current priorities are tracked outside this archived note; see Parent: [CueLoop Documentation](index.md) -This page preserves the April 2026 cleanup follow-up from `docs/audits/codebase-audit-2026-03-31.md`. It is not the active roadmap. +This page preserves the April 2026 cleanup follow-up from [codebase audit (2026-03-31)](archive/audits/codebase-audit-2026-03-31.md). It is not the active roadmap. Archived item: diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 32447275..0299f7ec 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -77,6 +77,31 @@ Fixes: - rerun with `make test` to use the project harness - inspect `crates/cueloop/tests/test_support.rs` helpers for deterministic setup +## Environment-dependent integration tests + +Symptom: a small set of `cargo test -p cueloop` integration tests fails on a fresh machine or CI image even though the default `make agent-ci` / `make ci` path is green upstream. + +### Git default branch is not `main` + +Several suites create disposable repositories with an explicit `main` branch (for example `git_init` in `crates/cueloop/tests/test_support/test_support_command.rs` runs `git init … -b main`). Parallel and merge-tree helpers then compare `HEAD` to `origin/main` after pushing to a bare `origin` remote (see `crates/cueloop/tests/parallel_done_json_safety_test/support.rs`). + +If your global Git default branch is not `main`, some local workflows can diverge from what those tests assume. + +Fix: + +```bash +git config --global init.defaultBranch main +``` + +### Doctor contract tests and the `pi` runner + +`crates/cueloop/tests/doctor_contract_test/` includes success-path checks such as `doctor_passes_in_clean_env` and `doctor_warns_on_missing_upstream`, plus `doctor_auto_fix_repairs_invalid_queue`. They run `cueloop doctor` in repos seeded from the cached `cueloop init --non-interactive` template (`seed_cueloop_dir` in `crates/cueloop/tests/test_support/test_support_command.rs`). That init writes `.cueloop/config.jsonc` with only top-level `"version": 2` (no `agent` stanza); after load, schema defaults apply so the effective agent runner is the built-in `pi` runner. Doctor therefore probes for a `pi` binary on `PATH`. + +Fix: + +- Install the `pi` runner CLI and ensure it is on `PATH` when you need those tests to pass locally, or +- Treat the failure as environment-specific when you are not working on doctor/runner diagnostics (repo `AGENTS.md` records the same constraint for Cursor Cloud images). + ## macOS App Build/Test Failures Symptom: xcodebuild failures or UI test runner signing/quarantine issues. diff --git a/docs/workflow.md b/docs/workflow.md index 0d19c5e9..5cf04d4c 100644 --- a/docs/workflow.md +++ b/docs/workflow.md @@ -1,273 +1,44 @@ -# Workflow and Architecture -Status: Active -Owner: Maintainers -Source of truth: this document for its stated scope -Parent: [CueLoop Documentation](index.md) +# Workflow (legacy hub) +Status: Active +Owner: Maintainers +Source of truth: navigation only — detailed content lives in linked guides +Parent: [Documentation index](index.md) -![3-Phase Workflow](assets/images/2026-02-07-workflow-3phase.png) - -Purpose: Explain CueLoop's high-level runtime layout, phases, and prompt override workflow without deep internals. - -## Runtime Files -- `.cueloop/queue.jsonc`: source of truth for active tasks. -- `.cueloop/done.jsonc`: archive of completed tasks. -- `.cueloop/config.jsonc`: project-level configuration. -- `.cueloop/prompts/*.md`: optional prompt overrides (defaults are embedded in the Rust CLI under `crates/cueloop/assets/prompts/`). -- `.cueloop/cache/parallel/state.json`: parallel run state (in-flight workers and terminal outcomes). - -## Prompt Overrides -CueLoop embeds default prompts in the Rust binary. To override prompts per repo, add: -- `.cueloop/prompts/worker.md` (base worker prompt) -- `.cueloop/prompts/worker_phase1.md` (Phase 1 planning wrapper) -- `.cueloop/prompts/worker_phase2.md` (Phase 2 implementation wrapper, 2-phase) -- `.cueloop/prompts/worker_phase2_handoff.md` (Phase 2 handoff wrapper, 3-phase) -- `.cueloop/prompts/worker_phase3.md` (Phase 3 review wrapper) -- `.cueloop/prompts/worker_single_phase.md` (single-pass wrapper) -- `.cueloop/prompts/completion_checklist.md` -- `.cueloop/prompts/phase2_handoff_checklist.md` -- `.cueloop/prompts/code_review.md` -- `.cueloop/prompts/task_builder.md` -- `.cueloop/prompts/scan.md` - -Overrides must preserve required placeholders (for example `{{USER_REQUEST}}` in task builder prompts). +This page exists for older links. Prefer the guides below for current workflow documentation. -## Three-Phase Workflow -Default execution uses three phases: -1. Phase 1 (Planning): plan is cached at `.cueloop/cache/plans/.md`. - - Plan-only violations prompt for action when `git_revert_mode=ask`; you can keep+proceed (explicit override), revert changes, or continue planning with a message. -2. Phase 2 (Implementation + CI): apply changes, run the configured CI gate command (this repo uses `make agent-ci`; generic fallback is `make ci`) when `agent.ci_gate.enabled=true`, then stop. When `agent.ci_gate.enabled=false`, only the CI command/requirement is skipped; implementation and Phase 2 handoff still continue. -3. Phase 3 (Review + Completion): review diff, resolve any flagged risks or suspicious leads before completion, re-run the configured CI gate command (this repo uses `make agent-ci`; generic fallback is `make ci`) when `agent.ci_gate.enabled=true`, complete task, and (when auto git commit/push is enabled) commit and push. When `agent.ci_gate.enabled=false`, Phase 3 still runs and reports configured CI validation as skipped by configuration. - - With auto git commit/push enabled, Phase 3 requires a clean repo to finish; for rejected tasks, allowed dirty files include `.cueloop/queue.{json,jsonc}`, `.cueloop/done.{json,jsonc}`, `.cueloop/config.{json,jsonc}`, and `.cueloop/cache/` (CueLoop bookkeeping/state). - -Phases can be set via `--phases` or `agent.phases` in config. - -## Parallel Run Loop (CLI Only) - -Parallel execution is available only via the CLI (`cueloop run loop --parallel [N]`). +![3-Phase Workflow](assets/images/2026-02-07-workflow-3phase.png) -High-level behavior: -- Each task runs in its own isolated git workspace clone under - `/.workspaces//parallel/` by default - (configurable via `parallel.workspace_root`). - Each workspace checks out the coordinator target base branch (for example `main`). -- Workers run configured phases, then execute an agent-owned integration loop: - `fetch/rebase/conflict-fix/commit/push`. -- Workers push directly to `origin/`; no PR/merge-agent lifecycle is used. -- State is persisted to `.cueloop/cache/parallel/state.json` for crash recovery and coordination. -- On startup, CueLoop prunes stale worker records before evaluating the state file's target branch. - If the target branch is missing or mismatched and there are no active workers, CueLoop auto-heals - the state file to the current branch. - Otherwise it fails with recovery guidance to avoid mixing active parallel runs across branches. +## Runtime layout -**Breaking change (2026-02):** The default directory for parallel workspaces changed from -`.worktrees/` to `.workspaces/`. The config key `parallel.worktree_root` has been renamed to -`parallel.workspace_root` and is no longer accepted. Run `cueloop migrate` to update existing -configs if you have custom `worktree_root` settings. +| Path | Role | +| --- | --- | +| `.cueloop/queue.jsonc` | Active tasks | +| `.cueloop/done.jsonc` | Completed / rejected tasks | +| `.cueloop/config.jsonc` | Configuration | +| `.cueloop/prompts/*.md` | Optional prompt overrides | +| `.cueloop/cache/plans/.md` | Phase 1 plan cache | +| `.cueloop/cache/parallel/state.json` | Parallel run state | -## Wait When Blocked (Sequential Loop) +Embedded defaults live under `crates/cueloop/assets/prompts/`. Overrides must keep required placeholders (for example `{{USER_REQUEST}}` in builder prompts). -When all remaining tasks are blocked by unmet dependencies (`depends_on`) or future schedules (`scheduled_start`), the sequential run loop normally exits with a summary of the blockers. Use `--wait-when-blocked` to keep the loop running and poll for changes instead. +## Execution model -Behavior: -- The loop polls `.cueloop/queue.jsonc` and `.cueloop/done.jsonc` for changes -- When a runnable task appears (dependencies complete or schedule passes), the loop continues -- Configurable poll interval (`--wait-poll-ms`, default: 1000ms, min: 50ms) -- Optional timeout (`--wait-timeout-seconds`, 0 = no timeout) -- Optional notification when unblocked (`--notify-when-unblocked`, desktop + webhook) -- Respects stop signals (`cueloop queue stop`) and Ctrl+C +| Topic | Document | +| --- | --- | +| Phase behavior (plan → implement → review) | [Phases](features/phases.md) | +| Architecture and trust boundaries | [Architecture](architecture.md) | +| Parallel workers and integration loop | [Parallel](features/parallel.md), [Architecture — parallel lifecycle](architecture.md#sequence-parallel-worker-lifecycle) | +| CI gates and git publish modes | [Supervision](features/supervision.md) | +| Prompt templates | [Prompts](features/prompts.md) | -Use this for "fire and forget" execution through dependent task chains without manual babysitting. +## Common commands -Examples: ```bash -# Wait indefinitely for dependencies/schedules to resolve +cueloop run one --phases 3 +cueloop run loop --max-tasks 5 +cueloop run loop --parallel 2 # experimental; see Parallel guide cueloop run loop --wait-when-blocked - -# Wait with a 10-minute timeout and notify when unblocked -cueloop run loop --wait-when-blocked --wait-timeout-seconds 600 --notify-when-unblocked -``` - -### Queue Unblocked Webhook Event - -When using `--notify-when-unblocked` with webhooks configured, CueLoop emits a `queue_unblocked` event: - -- `previous_status`: `"blocked"` -- `current_status`: `"runnable"` -- `note`: Summary counts like `ready=2 blocked_deps=3 blocked_schedule=1` - -This event is opt-in; add `"queue_unblocked"` to your webhook events list to receive it. - -## Continuous Mode (Sequential Loop) - -When the queue is empty, the sequential run loop normally exits. Use `--wait-when-empty` (alias `--continuous`) to keep the loop running and wait for new tasks instead. - -Behavior: -- If the queue is empty at startup, the loop does not exit; it waits for work -- If the loop runs out of candidates later, it waits instead of exiting -- Uses filesystem notifications (`notify` crate) to watch `.cueloop/queue.jsonc` and `.cueloop/done.jsonc` -- Falls back to polling if notifications fail -- Configurable poll interval (`--empty-poll-ms`, default: 30000ms = 30s, min: 50ms) -- No timeout in continuous mode (runs until stopped) -- Respects stop signals (`cueloop queue stop`) and Ctrl+C - -Combined with `--wait-when-blocked`, the loop provides "always-on" operation that handles both blocked tasks and empty queues. - -Use this for "set and forget" operation that integrates with system services (systemd, launchd). - -Examples: -```bash -# Continuous mode: wait indefinitely for new tasks -cueloop run loop --continuous - -# Poll more frequently (5s) for faster response -cueloop run loop --continuous --empty-poll-ms 5000 - -# Always-on mode: handle both blocked and empty states -cueloop run loop --continuous --wait-when-blocked -``` - -### Daemon Mode - -For background operation, use `cueloop daemon start|stop|status` (Unix-only): - -```bash -# Start daemon -cueloop daemon start - -# Check status -cueloop daemon status - -# View logs -cueloop daemon logs -# Live follow -cueloop daemon logs --follow - -# Stop daemon -cueloop daemon stop -``` - -The daemon is a thin wrapper around `cueloop run loop --continuous --wait-when-blocked` that: -- Detaches from the terminal -- View logs with `cueloop daemon logs` -- Manages PID/state files in `.cueloop/cache/` -- Responds to `cueloop daemon stop` and `cueloop queue stop` - -See `docs/cli.md` for systemd and launchd service templates. - -## Security and Redaction - -### Safeguard Dumps -When operations fail (runner errors, scan validation failures), CueLoop writes safeguard dumps to temp directories for troubleshooting. These dumps are **redacted by default** to prevent secrets from being written to disk. - -**Important**: Redaction is pattern-based and best-effort. It may miss secrets in unexpected formats, encoded data, or novel patterns. Always review dumps before sharing. - -**Redaction applies to:** -- API keys and bearer tokens -- AWS access keys (AKIA...) -- SSH private keys -- Hex tokens (32+ characters) -- Sensitive environment variable values - -**Raw dumps** are only written when explicitly opted in via: -- `CUELOOP_RAW_DUMP=1` or `CUELOOP_RAW_DUMP=true` environment variable -- `--debug` flag (implies verbose output desired; also enables raw debug logs) - -**Never commit safeguard dumps** to version control, even when redacted. - -### Debug Logging -When `--debug` is enabled, raw runner output is written to `.cueloop/logs/debug.log`. This is intentional for troubleshooting but may contain unredacted secrets captured before redaction is applied. - -**Important:** Console output is redacted via `RedactedLogger`, but debug logs capture raw log records and runner streams before redaction. Debug logs should be treated as highly sensitive and never committed. - -**Best practices:** -- Only use `--debug` when necessary for troubleshooting -- Treat `.cueloop/logs/debug.log` as sensitive data -- Ensure `.cueloop/logs/` is in `.gitignore` -- Clean up debug logs after use: `rm -rf .cueloop/logs/` - -## Runner Model Control -Runner and model selection are driven by a combination of CLI flags, task overrides, and config. The CLI has the highest priority for a single run. - -## Session State - -Session state is persisted to `.cueloop/cache/session.jsonc` for crash recovery. It includes: -- Task ID and session metadata -- Iteration and phase progress -- **Per-phase runner/model settings** (for display in recovery prompts) - -Note: Per-phase settings are informational only. Crash recovery recomputes settings from CLI flags, config, and task overrides to ensure consistency. - -## Webhook Events - -CueLoop can emit webhook events for external integrations (Slack, Discord, CI systems, dashboards). Webhooks are configured via `agent.webhook` in config. - -### Event Types - -**Task Events** (enabled by default): -- `task_created`: Task added to queue -- `task_started`: Task execution begins -- `task_completed`: Task finished successfully -- `task_failed`: Task failed or was rejected -- `task_status_changed`: Generic status transition - -**Loop Events** (opt-in): -- `loop_started`: Run loop begins (includes repo/branch/commit context) -- `loop_stopped`: Run loop ends (includes duration and summary) - -**Phase Events** (opt-in): -- `phase_started`: Phase execution begins (includes runner/model/phase context) -- `phase_completed`: Phase execution ends (includes duration and CI gate outcome) - -### Opt-in Behavior - -New event types (`loop_*`, `phase_*`) are **opt-in** and not enabled by default. To receive these events, explicitly configure them: - -```json -{ - "agent": { - "webhook": { - "enabled": true, - "url": "https://example.com/webhook", - "events": ["loop_started", "phase_started", "phase_completed", "loop_stopped"] - } - } -} -``` - -Use `["*"]` to subscribe to all events including new ones. - -### Runner Session Handling (Kimi) - -![Session Management](assets/images/2026-02-07-session-management.png) - -CueLoop uses explicit session management for runners that support it (notably **Kimi**): - -**Session ID Generation** -- Format: `{task_id}-p{phase}-{timestamp}` -- Example: `RQ-0001-p2-1704153600` -- Each phase (1, 2, 3) gets its own unique session ID - -**Why Explicit Sessions?** -- **Deterministic**: Same ID always resumes the same session -- **Reliable**: No dependency on parsing JSON output or runner-specific `last_session_id` tracking -- **Debuggable**: Human-readable IDs make it easy to trace session lifecycle -- **Isolated**: Each phase has its own session, preventing context leakage between planning, implementation, and review - -**Command Examples** -```bash -# Phase 2 initial invocation -kimi --print --output-format stream-json --model kimi-for-coding \ - --session RQ-0001-p2-1704153600 \ - --prompt "Implement the plan..." - -# Phase 2 continue (CI failure retry) -kimi --print --output-format stream-json --model kimi-for-coding \ - --session RQ-0001-p2-1704153600 \ - --prompt "Fix the CI errors..." ``` -**Implementation Notes** -- CueLoop generates the session ID at phase start and reuses it for all continue operations within that phase -- The session ID is stored in `ContinueSession` for CI gate retry loops -- If Kimi crashes and the session becomes corrupted, CueLoop will attempt to resume with the same ID (user accepts this risk) +Sequential loop with `--wait-when-blocked` polls the queue when tasks are blocked by dependencies or `scheduled_start` instead of exiting immediately.