Skip to content

SOW.md

Latest commit

 

History

History
189 lines (159 loc) · 9.19 KB

SOW.md

File metadata and controls

189 lines (159 loc) · 9.19 KB
Raw

SOW: AI-Orchestrated Development Workflows

Business Context

Software teams increasingly use AI coding assistants, but each interaction is ad hoc — prompts are improvised, outputs are untracked, and multi-step workflows require constant human shepherding. There is no repeatable way to define a body of work, feed it through AI-powered routines, and get reliable, auditable results.

Decree solves this by treating AI work like database migrations: define the work declaratively, process it through configurable routines, and track everything that happened. Teams get structured, reproducible AI workflows that scale from a single spec to an entire project built from ordered migration files.

Jobs to Be Done

  1. When I have a body of work to accomplish, I want to break it into ordered migration files, so each piece is processed sequentially with full context from prior steps.

  2. When I run a migration, I want it routed to the right AI routine automatically, so I don't manually invoke different tools for different tasks.

  3. When a routine fails, I want automatic retries with prior attempt logs available as context, so transient failures resolve without my intervention.

  4. When I need a multi-step workflow (research, then generate, then verify), I want routines to chain follow-up messages, so complex pipelines run end-to-end without manual orchestration.

  5. When I want to track what AI actually did, I want every execution logged in run directories with message history, so I can audit, debug, and reproduce results.

  6. When I need ongoing automated work, I want cron-scheduled messages processed by a daemon, so recurring tasks run without manual triggers.

  7. When I'm starting a new project, I want guided setup that scaffolds routines, prompts, and config, so I'm productive immediately without learning the file layout by hand.

  8. When I want to interact with AI directly, I want templated prompts with project context injected, so my conversations start with the right information already assembled.

User Scenarios

  • Greenfield project build: A developer runs decree init, selects their AI tool, then writes 10 migration specs describing a new CLI application. Running decree process executes each spec in order — the develop routine invokes the AI, which reads each spec, implements the code, and verifies acceptance criteria. The developer reviews results after each migration via decree log and decree status.

  • Multi-step analysis pipeline: A business analyst creates specs for three startup ideas. Each spec routes to a market-analysis routine that chains to competitive-landscape, then financial-model, then executive-summary. One decree process command produces a complete evaluation for each business — four documents per idea, fully automated.

  • Creative asset generation: An artist writes specs describing historical figures and art styles. Processing chains through research, prompt-crafting, and image generation routines. Each step passes artifacts to the next via the run directory, producing finished portraits with no manual handoffs.

  • Recurring scheduled work: A team configures a cron message that runs weekday mornings. The daemon picks it up, routes it through a code-review routine, and deposits results in the run directory. The team checks decree log when they arrive.

  • Interactive prompt sessions: A developer runs decree prompt migration to plan the next batch of work. The prompt template injects current project state — processed migrations, available routines, config — into the clipboard or launches the AI interactively with full context.

  • Retry and dead-lettering: A routine fails due to a flaky API. Decree retries up to the configured limit, passing prior attempt logs so the AI can adjust its approach. If all retries exhaust, the message is dead-lettered for manual review rather than silently dropped.

Scope

In scope:

  • Project initialization with AI tool selection and scaffolding
  • Migration-driven processing pipeline with alphabetical ordering
  • Message system with YAML frontmatter, chain/sequence tracking, and routing
  • Shell-based routine system with pre-checks, custom parameters, and chaining
  • Lifecycle hooks (beforeAll, afterAll, beforeEach, afterEach, onDeadLetter)
  • Retry with configurable max attempts and dead-letter queue
  • Per-routine max_retries and timeout_s configuration overrides
  • DECREE_TRIGGER, DECREE_FINAL_ATTEMPT, and DECREE_PREVIOUS_SESSION_ID env vars
  • Claude token-exhaustion detection with automatic wait-and-retry
  • Claude session resume (DECREE_PREVIOUS_SESSION_ID) after token-exhaustion wait
  • Migration dead-letter stops the process loop and exits non-zero
  • Machine-readable run.json written to each run directory
  • Cron scheduling and daemon mode for continuous operation
  • decree cron list command for live schedule inspection
  • Run directory logging and execution audit trail
  • Prompt templates with variable substitution and project context injection
  • CLI for process, prompt, routine, verify, daemon, status, log, init, help, cron list, skill
  • Git stash hooks for change isolation per routine execution
  • decree skill command for AI assistant integration (Claude and Copilot)

Out of scope (future work):

  • Built-in AI providers (decree invokes external tools, not APIs directly)
  • Web UI or dashboard for monitoring
  • Multi-project orchestration or cross-repo workflows
  • Parallel migration processing (sequential by design)
  • Built-in version control beyond optional git stash hooks
  • User authentication or team access control

Deliverables

  1. CLI binary (decree) with subcommands for the full workflow lifecycle
  2. Project scaffolding via decree init with AI tool selection
  3. Migration processing pipeline with inbox/outbox message passing
  4. Routine system with shell scripts, pre-checks, parameter discovery, and chaining
  5. Lifecycle hook system for cross-cutting concerns (git stash, notifications, onDeadLetter for dead-letter events)
  6. Daemon with cron-based scheduling, inbox polling, and decree cron list for live schedule inspection
  7. Prompt template system with context-aware variable substitution
  8. Execution logging with run directories, attempt tracking, machine-readable run.json, and dead-letter queue
  9. AI skill installation via decree skill for Claude and GitHub Copilot
  10. Example projects demonstrating different workflow patterns

Acceptance Criteria

  • Running decree init in an empty directory produces a working project structure with config, routines, prompts, and router
  • Migration files in .decree/migrations/ are processed in alphabetical order, each exactly once, tracked in processed.md
  • A routine can chain follow-up messages that are processed depth-first before the next migration
  • Failed routines retry up to max_retries times with prior logs available, then dead-letter
  • decree process --dry-run lists pending work without executing anything
  • decree verify runs all routine pre-checks and reports readiness
  • decree daemon continuously monitors cron schedules and inbox for new messages
  • decree prompt assembles templates with project context and offers clipboard copy or interactive AI launch
  • decree status shows processing progress; decree log shows execution output
  • Lifecycle hooks fire at the correct points with the documented environment variables
  • SIGINT during processing exits cleanly (code 130) without running further retries or hooks
  • The tool is AI-agnostic — routines invoke whichever AI tool the user configures
  • Per-routine max_retries overrides the global value for that routine; timeout_s kills the process after the given seconds and treats it as exit 1
  • onDeadLetter hook fires exactly once when a message exhausts retries; does not fire on beforeEach failure
  • DECREE_TRIGGER is set in routines and all hook phases to inbox, cron:<stem>, or chain
  • DECREE_FINAL_ATTEMPT=true is present in afterEach on the last attempt only
  • run.json is written to the run directory after every completed run (success or dead-letter)
  • decree cron list shows all cron files with schedule, last-run age, and next-fire countdown
  • decree skill --scope project --target claude installs .claude/skills/decree/SKILL.md
  • decree skill --scope project --target copilot installs .github/copilot-instructions.md
  • Token-exhaustion detection pauses processing, waits until the reset time, then retries the migration
  • SIGINT during a token-exhaustion wait exits with code 130
  • A migration that is dead-lettered stops decree process immediately; subsequent migrations do not run

Assumptions & Constraints

  • Users have a Unix-like shell environment (bash) for routine execution
  • At least one AI CLI tool (claude, copilot, opencode, etc.) is installed and accessible on PATH
  • Migration files are markdown with optional YAML frontmatter
  • Processing is sequential and single-threaded by design — ordering guarantees matter more than throughput
  • Decree orchestrates AI tools but does not embed or bundle any AI provider
  • Git is available if git stash hooks are configured, but git is not required for core functionality