Agentic Workflow CLI

@inspiracode/agentic-workflow is a command-line tool for Agentic Workflow Development.

The goal of Agentic Workflow Development is to leverage AI agents to automate, structure, and optimize the software development lifecycle. The CLI coordinates work between humans, AI agents, deterministic scripts, and reusable skills.

It is organized around two roles:

• Planner — turns requirements into a refined backlog on a GitHub Project v2.
• Developer — picks up issues from the backlog and ships them through self-review, PR, peer review, merge, and cleanup.

A single install gives you both role surfaces. Whether a command behaves as planner or developer is inferred from the current working directory.

Install

During alpha the CLI is not published to npm — install from a git clone and build it:

git clone https://github.com/inspiraCode/agentic-workflow.git /opt/agentic-workflow
cd /opt/agentic-workflow && corepack enable && pnpm install && pnpm build
sudo ln -sf /opt/agentic-workflow/dist/cli.js /usr/local/bin/agentic   # on every user's PATH
agentic --version

On a single-user laptop you can npm link inside the clone instead of the shared symlink. Keep the clone current with agentic upgrade (git pull + rebuild in place); because the shared symlink points at the rebuilt dist/cli.js, one upgrade updates all users. Run agentic upgrade --remote to rebuild your default server's CLI over SSH.

Then bootstrap your shell:

agentic shell install        # writes a minimal alias set to your rc file

The CLI is flattened: the daily verbs are top-level — agentic start|auto|loop|review|pr|finish|sprint|draft|board|monitor — with agentic dev|plan|server <…> keeping the less-common commands. shell install adds a catch-all a (→ a loop, a review 123) plus role-prefixed alias families — plan-* (plan-draft, plan-promote, plan-sprint, …), dev-* (dev-start, dev-auto, dev-review, …), and monitor-* (monitor-up/down/status, plus a bare monitor for the live dashboard) — and acd / dev-cd functions (cd into a worktree). Run agentic shell init zsh|bash|pwsh to print the full list. Run execution verbs on a server by default with agentic target remote (override per-call with --local/--remote).

Required tools on PATH: Node ≥ 20, git ≥ 2.40 (for git worktree), and gh (the GitHub CLI) authenticated with repo, project, and workflow scopes.

Core Concept

This tool combines three elements:

1. AI agents for reasoning-heavy tasks: planning, implementation guidance, code review, decision-making.
2. Deterministic scripts for mechanical operations that should run reliably without spending agent tokens: creating worktrees, fetching issue context, flipping Project Status fields, opening PRs, archiving artefacts, merging + cleanup.
3. Reusable skills — markdown files installed under .github/skills/ that give AI agents the conventions, rubrics, and command map for this workflow.

Splitting the work this way keeps the agent context focused on the parts that benefit from reasoning, reduces token spend, and makes the pipeline reproducible across people and machines.

Why Agentic Workflow Development?

Traditional workflows make a developer manually move between planning, issue creation, implementation, review, PR management, and cleanup. Each step has its own ceremony and its own opportunities to forget something.

Agentic Workflow Development collapses that ceremony into a small set of CLI commands and a small set of skills. The result:

• Planning is more structured.
• Issues are written to be consumable by both humans and AI agents (agent_meta block: feature_flag, run_commands, self_check, blocked_by).
• Per-ticket development context is collected automatically into a gitignored .agent-context/ directory inside the worktree.
• Repetitive operations are scripted.
• Token usage is reduced — agents only see what they need.
• Reviews can be run by AI agents, humans, or both.
• PR state, GitHub Project Status, and the local mirrored board stay in sync.

Concept: solutions

A solution groups one or more repos that ship together (e.g. an API, a web app, and a mobile app) plus the GitHub Project v2 that tracks their work. The solution is described by a single solution.yml at the root of the solution directory:

name: my-product
worktreeRoot: ./worktrees
github:
  owner: my-org
planner:
  projectNumber: 11
  projectId: PVT_…
  fields: { Status: PVTSSF_…, Priority: PVTSSF_…, Sprint: PVTIF_…, Size: PVTSSF_… }
  statusOptions: { … }
  sprints:
    - { number: 30, id: a9df494d, start: 2026-05-30, end: 2026-06-13 }

The planner-owned artefacts (board/, backlog/, manifests/, conventions/, review/) live at the top of the solution directory. Each target repo is added as a folder in <name>.code-workspace with role, repo, and (optional) defaultBranch extras — that file is the source of truth for which repos belong to the solution.

You may organize repos on disk however you like. The CLI discovers the active solution via:

1. --solution <name> flag (looks up the global registry), or
2. Walking up from the current working directory looking for solution.yml, or
3. The default solution recorded in the global registry at ~/.config/agentic-workflow/solutions.json.

Bootstrap a new solution:

mkdir ~/solutions/my-product && cd ~/solutions/my-product
agentic solution init   # (formerly `agentic init`, still works) interactive: solution name, GH
                    # owner, default branch, worktree root, link/create the GitHub Project v2,
                    # install bundled skills + docs, git-init + commit, optional shell aliases.
                    # Team setup: `solution users` → `solution provision` (admin) → `solution onboard` (each dev).
                    # If a planner project is configured, it also runs `plan sync --pull`
                    # for the current sprint to seed board/<status>/.

Switch between solutions:

agentic solution list
agentic solution switch <name>
agentic --solution <name> plan list

Roles

Planner

The Planner transforms user requirements into actionable work items and organizes them into a prioritized backlog on a GitHub Project v2.

1. Ideation

The planner generates a list of potential features based on the requirements provided by the user. Each ideation lands as a free-form markdown file under backlog/ideation/. These ideas describe what the software should do and serve as the starting point for the workflow. The bundled skill agentic-ideation codifies the format and prompts an agent to author them.

2. Drafting

Selected ideas are transformed into one or more issue drafts under backlog/drafts/. Unlike traditional issue descriptions, these drafts are written to be consumed by both humans and AI agents. Each draft includes:

• Goal + Context
• agent_meta block (feature_flag, run_commands, self_check, blocked_by)
• Acceptance Criteria
• Definition of Done
• Suggested implementation steps + technical notes

Drafts are batched into a TSV under manifests/. The bundled skill agentic-spec-writer codifies the format.

3. Backlog upload

plan-draft (alias for agentic draft) sweeps every TSV under manifests/, creates each row as a GitHub Project v2 draft item, converts it to a real GitHub Issue, and archives the draft markdown into board/backlog/. The local board/<status>/ tree is the mirror of the Project's Status field.

The planner is responsible for:

• Prioritizing the backlog
• Organizing issues into sprints (plan-roll-sprint carries unfinished items between iterations)
• Making sure each issue is clear and actionable
• Ensuring issues contain enough context for both developers and AI agents
• Optionally refreshing the local board/ mirror via the manual plan-sync (the GitHub Project itself is the source of truth — commands read it directly)

At this point, issues are ready to be picked up by developers.

Developer

The Developer picks up an issue, implements it, runs a self-review, opens a PR, supports peer review, and finalizes the ticket.

1. dev-start

Starts work on an issue:

dev-start                   # no args → interactive picker over the Project's Todo items
dev-start <issue#>          # or <issue-url>, draft node id, or Project URL

With no argument the command opens a checkbox picker listing every Todo item read straight from the GitHub Project (one cached bulk query — no per-ticket lookups). Up to 5 dependency-free, unassigned-by-others tickets are pre-checked (override with --limit <n>); tickets that already have a non-@me assignee are disabled ([assigned: @other]) and tickets with open agent_meta.blocked_by show a [blocked by: #N] badge. Checked tickets are then started in parallel — every one gets its own worktree + .agent-context/ via the same flow as the single-ticket form, with git operations on the same repo serialized internally. A live dashboard shows one status line per ticket (current step, elapsed time, ✓/✗); cap parallelism with --concurrency <n> or fall back to the old one-at-a-time behavior with --sequential.

One more batch mode:

• --open-code — opens one VS Code window per ticket with the autopilot pipeline running visibly in that window's integrated terminal (via a folderOpen task in .vscode/tasks.json; requires VS Code to allow automatic tasks, which the command configures per-worktree). Combinable with --auto — the window's task runs the pipeline, so nothing extra runs in-process.

In --auto batches the per-ticket agent output is not interleaved on screen — it streams to <worktree>/.agent-context/auto/*.log, and every step transition is also written to <worktree>/.agent-context/auto/progress.json so you can follow any ticket with tail -f or a quick cat.

Whether single-ticket or batch, the command:

• Creates a git worktree at <worktreeRoot>/<repo>/<n>-<slug>/ on a per-ticket branch (<type>/<feature>/<n>-<title-kebab>), forked from the repo's defaultBranch from the workspace.
• Refuses to start if the issue is assigned to someone other than @me (override with --force, which prints a "Taking over from @x" warning).
• Refuses to start if any numeric agent_meta.blocked_by issue is still open (override with --force).
• Self-assigns the GitHub issue.
• Flips the Project Status field to In Progress (best-effort).
• Runs dev-context to populate .agent-context/:
  • issue.md — full GH issue body
  • comments.md — issue comment thread
  • AGENT_PROMPT.md — tailored prompt with branch, base, touch paths, run commands, self-check
• Stamps branch / worktree / started_at into the matching board archive on the solution branch and autocommits.
• Opens the worktree in a new VS Code window (mode: code / cursor / none).
• Auto-approve: writes <worktree>/.vscode/settings.json with VS Code Copilot Chat / agent-mode auto-approve defaults so the inner dev loop (lint, test, read-only git, fs inspection) runs unattended without "Allow this terminal command?" prompts. Toggle off per-call with --no-auto-approve, or globally for the solution by adding dev.autoApprove: false to solution.yml.
• Headless mode (--headless): skips the VS Code launch and spawns an agent CLI directly against the worktree (fire-and-forget). Logs go to .agent-context/run.log, the child PID to .agent-context/run.pid. Pick CLI/model layered (highest first): --profile <name> → --agent <id> (+ --model) → agent_meta.agent_profile → agents.routing.byRole[<repoRole>] → agents.default. Built-in CLIs: claude (Claude Code) and opencode. The auto fallback prefers claude when it is on PATH, otherwise opencode. When the resolved profile leaves model empty, opencode defaults to openrouter/minimax/minimax-m3 (MiniMax-M3) and runs with --dangerously-skip-permissions so unattended implementation, commits and self-reviews don't get blocked by permission prompts — override either with solution.yml agents.* or with --model <id> per call. For any other CLI, declare a profile in solution.yml with cli: external + command + args[] (placeholders: {promptFile}, {promptContent}, {model}, {cwd}, {logFile}).
• Auto mode (--auto): runs the full autonomous pipeline per ticket — see Autonomous pipeline below. When the no-arg picker is used without a mode flag, a follow-up menu asks how to start the selected tickets (VS Code / headless / full auto / one terminal per ticket / one VS Code window per ticket).

The developer (or AI agent) then implements the change inside the worktree.

At any point, dev list shows everything currently in flight — one row per worktree with the issue number, repo, Project status, branch, PR state, and live autopilot progress (read from each worktree's .agent-context/auto/progress.json). dev list --json emits the same data machine-readably.

1a. dev-agent

Get or set the default agent CLI + model for this solution. Persists to solution.yml. Built-in CLIs: claude (Claude Code) and opencode — the auto fallback prefers claude when it is on PATH, otherwise opencode. When the resolved profile leaves model empty, opencode defaults to openrouter/minimax/minimax-m3 (MiniMax-M3).

dev-agent                                          # interactive menu: pick CLI then model
dev-agent --print                                  # non-interactive read-out of the current config
dev-agent --pick-agent                             # run only the CLI step of the menu
dev-agent --pick-model                             # run only the model step of the menu (uses the current CLI)
dev-agent --agent opencode --model openrouter/minimax/minimax-m3   # set both directly
dev-agent --agent opencode                          # only change the cli
dev-agent --model openrouter/minimax/minimax-m3    # only change the model
dev-agent --profile backend                         # copy agents.profiles.backend into default
dev-agent --profile backend --model claude-fable-5  # copy profile, override the model
dev-agent --reset                                   # clear agents.default (falls back to built-in `auto`)

Running dev-agent with no flag opens an interactive picker (CLI then model, sourced from agents.models). In a non-TTY shell (piped output, CI, etc.) it falls back to printing the current config and points you at --print / --agent / --model / --profile / --reset for non-interactive use.

agentic init seeds agents.models with the default catalog: MiniMax-M3, Claude Sonnet 4.6, Opus 4.7, Fable (each entry is a built-in label resolved at pick time to the right model id for the chosen CLI — openrouter/minimax/minimax-m3 for opencode, claude-fable-5 for claude, etc.). Edit agents.models in solution.yml to add or remove entries; the pickers read straight from this list and fall back to the built-in defaults when it's empty.

The CLI is layered (highest first): --profile <name> → --agent <id> (+ --model) → agent_meta.agent_profile → agents.routing.byRole[<repoRole>] → agents.default → built-in auto fallback. Per-call flags (dev-start 42 --auto --agent opencode --model …) override for that one run; dev-agent changes the persistent default for every subsequent run. agentic solution current also shows the effective agents config in its output.

2. dev-commit

After (or during) implementation, turn the working tree into well-organized commits:

dev-commit                  # builds a commit-organizer prompt and copies it to the clipboard
dev-commit --run            # runs the agent CLI (Claude Code by default) to make the commits now

The prompt embeds git status, the uncommitted diff (lockfiles excluded), a sample of recent commit subjects, and any detected commit conventions — commitlint configs (commitlint.config.*, .commitlintrc*, package.json#commitlint), husky hooks, and .gitmessage templates. The agent groups related changes into one or more well-scoped commits that pass the repo's commit linters (never --no-verify). This matters because dev-self-review diffs the branch against its base — the implementation must be committed before it can be reviewed.

Automatic formatting (no agent tokens)

Before the commit prompt is built (and before dev-pr pushes), the CLI runs the repo's formatter outside the agent — the agent always sees an already-formatted diff and never spends tokens on style. The command resolves per repo:

1. An explicit format extra on the repo's folder entry in <name>.code-workspace (e.g. "format": "pnpm run format"; set "format": "none" to disable).
2. Otherwise auto-detected: a format script in package.json (run with the detected package manager) → a Prettier config → gofmt -w . (go.mod) → cargo fmt (Cargo.toml) → dotnet format (*.sln/*.csproj) → ruff format . / black . (pyproject.toml).
3. Nothing detected → formatting is skipped silently.

Skip per call with --no-format (on dev commit and dev pr). Tip: point format at a scoped script (e.g. one that formats only changed files) if a whole-repo formatter would create noisy first-run diffs.

3. dev-self-review

After implementation, run a pre-PR self-review:

dev-self-review

This command does NOT generate a report itself. Instead, it runs the repo's test suite outside the agent (an explicit test extra on the repo's .code-workspace folder entry, e.g. "test": "pnpm test", "none" disables; otherwise auto-detected: package.json test script → go test ./... → cargo test → dotnet test → pytest; skip per run with --no-tests) and assembles a self-review prompt — the canonical rubric from <solution-root>/review/REVIEWER_PROMPT.md plus the test results, base/head SHAs, the full git diff, and .agent-context/issue.md — and copies it to the clipboard. The reviewer must reproduce the test results in its report, and a failing suite forces ready_for_pr: false. The developer pastes the prompt into a fresh AI agent session, which writes:

• reviews/<branch>/<YYYY-MM-DD>-review-<N>.md — review file with YAML frontmatter ready_for_pr: true | false (and an optional verdict), followed by Critical / High / Medium / Low / Nit / Praise sections.
• .agent-context/pr-content.md — the PR body (Closes #<n>, Goal, AC checklist, DoD, changes outside the plan).

reviews/<branch>/ is tracked (NOT gitignored) so the review history travels with the branch.

4. dev-pr

Once the self-review file says ready_for_pr: true, open the PR:

dev-pr                      # --force to bypass the gate; --base <ref> to override the base

This command:

• Reads the latest reviews/<branch>/... file and refuses to open the PR unless ready_for_pr: true (override with --force).
• Resolves the base branch from --base → BASE_REF env → the repo's defaultBranch in .code-workspace/solution.yml → origin/HEAD → dev.
• Runs the repo formatter (see "Automatic formatting" below) and auto-commits any resulting changes (style: apply formatting) before pushing. Skip with --no-format.
• Creates the PR directly via gh pr create and prints the URL — no browser click needed. --draft opens it as a draft; --web opts back into the browser form. Body comes from .agent-context/pr-content.md (legacy fallback: PR_BODY.md).
• With --publish-reviews, posts each reviews/<branch>/… file on the PR: a comment with a human-readable summary (verdict + finding counts + headline findings) and the full report uploaded as a secret gist (falls back to embedding the report when gists are unavailable). Idempotent: already-published reviews are skipped.
• On success, flips the Project Status to In Review — the Project board reflects it immediately; no local sync step runs.

5. Peer code review

Opening a PR can trigger a configured pr-agent GitHub Action (the bundled solution/review/pr-agent.workflow.yml) for an automated first-pass review. Other developers can run dev-review to perform a deeper review — as a clipboard handoff to their own agent, or fully agent-driven with --run:

dev-review                    # picker: choose teammates' open PRs to review (multi-select)
dev-review <pr-url>           # prep one PR: stage prompt → clipboard / VS Code handoff
dev-review <pr#> --run        # agent writes the verdict report AND submits a GitHub review
dev-review 8 9 10 --run       # review several PRs in PARALLEL (live dashboard)
dev-review <pr#> --run --no-post     # agent writes the report locally, don't upload
dev-review 123 --repo owner/name --run   # any PR in any repo (no solution needed)

Like dev-start, dev-review takes one or more PRs (numbers or URLs) and reviews them in parallel with a live per-PR dashboard (--concurrency <n> to cap, --sequential for one-at-a-time). With no argument it shows a checkbox picker of open PRs authored by others across the solution's repos. On the 24/7 server: agentic server run prod -- dev review 8 9 10 --run (and the review worktrees show up in dev list / dev monitor / server status tagged review #<pr>, with phase/tokens/cost).

dev-review works for any repository and any PR — even repos that don't use agentic workflow (it resolves the repo from --repo, a PR URL, or the clone you're cd'd into; the rubric falls back to a bundled default). It:

• Resolves the PR via gh pr view and checks the PR head branch out into a worktree so the reviewer (or AI agent) has the full codebase, not just the diff. It reuses the current worktree if you are already on that branch, reuses an existing sibling worktree under <worktreeRoot>/<repo>/, or creates <worktreeRoot>/<repo>/review-<n>-<slug> via git worktree add --track.
• Runs the PR head's test suite outside the agent (same test extra / auto-detection as dev-self-review; skip with --no-tests) and embeds the results in the review prompt.
• Stages <worktree>/.agent-context/review-<pr#>/{REVIEW_PROMPT.md, diff.patch, pr.json, tests.txt}.
• Default (handoff): auto-copies REVIEW_PROMPT.md to the clipboard and opens the worktree in VS Code.
• --run (agent-driven): runs the configured agent CLI (--agent/--model/--profile, else the solution default / built-in auto) against the peer review prompt — which is review-only, so it never fixes the diff or writes a PR body. The agent writes the report to reviews/<head-branch>/<date>-review-N.md with ready_for_pr + verdict frontmatter. Unless --no-post, it is then submitted to the PR as a formal GitHub review: the full report is uploaded as a secret gist, and gh pr review posts a summary (verdict + finding counts + headline findings + gist link) with the review status mapped from the verdict — approve → APPROVED, request_changes → CHANGES_REQUESTED, hold/unknown → COMMENTED. This sets the PR's review decision and records the gh-authenticated user as a reviewer (so it clears a pending review request). It's idempotent (a reviews/<branch>/<file> marker is checked against existing reviews) and falls back to a plain COMMENTED event when GitHub forbids the decision (e.g. reviewing your own PR). Use --add-reviewer <logins> to also request additional human reviewers. Headless-friendly (no clipboard/VS Code), so it runs on a 24/7 server via agentic server run <name> -- dev review <pr#> --run.

The reviewer rubric is resolved from (in order): --prompt override → <solution-root>/review/REVIEWER_PROMPT.md → .github/agents/REVIEWER_PROMPT.md → walk-up ../review/REVIEWER_PROMPT.md → <repo-top>/.github/agents/REVIEWER_PROMPT.md → ~/.config/agentic-workflow/REVIEWER_PROMPT.md → bundled fallback.

6. dev-finish — merge & cleanup

After the PR is approved and CI is green:

dev-finish                  # --merge-method squash|merge|rebase (default squash)
                            # --force adds --admin to the merge and tears down even on failure

This command:

• Verifies the worktree only has scaffolding-files dirty, has no unpushed commits, and that a PR exists for the branch.
• Merges the PR via gh pr merge --squash --delete-branch (override the strategy with --merge-method). Already-merged PRs short-circuit; closed-not-merged PRs warn and continue.
• Snapshots .agent-context/ into the board archive's .notes/ dir (when a local board/ mirror exists) before teardown.
• Tears down the worktree (git worktree remove --force) and deletes the local branch.
• Flips the Project Status to Done, closes the linked Issue (with the merged-PR link), and runs the Blocked→Todo unblock pass for any project items whose agent_meta.blocked_by issues are now all closed.

dev-finish is self-contained — no follow-up plan-sync is needed. Run plan-sync by hand only if you want to refresh the optional local board/<status>/ mirror.

Need to abandon or restart a ticket instead of finishing it? Use dev-remove:

dev-remove [<n>]            # tear down the worktree WITHOUT merging
                            # --backlog flips Status → Backlog instead of Todo
                            # --delete-branch also drops the local branch
                            # --force bypasses the uncommitted/unpushed gates

It applies the same safety gates as dev-finish, snapshots .agent-context/ into the board notes, removes the worktree, keeps the branch by default (a later dev-start <n> recreates the worktree on the same branch and resumes the work), and flips the Project Status back to Todo (or Backlog). It also cleans up after a manual git worktree remove/rm -rf: run dev-remove <n> and it prunes the stale git metadata and still flips the status.

Need to throw the current attempt away and start the implementation over from scratch? Use dev-reset (alias agentic reset):

agentic reset [<n>|<issue-url>|<pr-url>]   # full destructive reset → Todo
                                           # --yes skips the confirm prompt
                                           # --local / --remote force the side

Unlike dev-remove, dev-reset is unconditionally destructive: it closes any open PR (gh pr close --delete-branch), SIGTERMs the running agent in the worktree, removes the worktree, deletes the local + remote branches, unassigns every user from the issue, and flips Project Status → Todo. It accepts a bare issue number, an issue URL, a PR URL (resolved to its ticket via closingIssuesReferences → Closes #N → branch parse), or no arg (cwd). An interactive y/N confirm with a summary of what will be destroyed gates every run; --yes skips it and is required on non-TTY shells (CI, server run, …). The command is remote-aware: when the ticket's worktree isn't on this machine and a server is configured, it auto-forwards to the default server (override with --local / --remote).

7. dev-release

Cuts a release PR (dev → main by default) prefilled with the commit range and the merged feature-PR list.

Autonomous pipeline (dev-start --auto / dev-auto)

With Claude Code (or any configured agent CLI) installed, the whole developer loop can run unattended:

dev-start --auto            # picker → autonomous pipeline per selected ticket
dev-start 42 --auto         # single ticket
dev-auto --from review      # resume the pipeline on the current worktree from a step

Per ticket, the pipeline runs sequentially and audited (every prompt + log lands in .agent-context/auto/):

1. Implement — the agent CLI runs with .agent-context/AGENT_PROMPT.md as its prompt, directly in the new worktree.
2. Commit — the dev-commit agent pass groups the changes into well-scoped commits that pass the repo's commit linters (required: the self-review diffs against the base branch).
3. Review — dev-self-review assembles the review prompt (rubric + diff + ticket) and a fresh agent run writes reviews/<branch>/<date>-review-1.md + .agent-context/pr-content.md.
4. Fix (one iteration) — when the review says ready_for_pr: false or carries Critical/High/Medium findings, the agent gets one pass to fix the findings, update pr-content.md, record deferred items in todos.tasks, and commit. A second review pass then validates the fixes.
5. PR + human handoff — the PR is created non-web (gh pr create) and every review file is posted as a PR comment, so humans see exactly what was done automatically and can agree, adjust, or push back. If the final review still isn't ready, the PR is opened anyway (flagged) so a human can take over.

The agent CLI is resolved per ticket like headless mode (--agent claude, --model, --profile, agents.* routing); the built-in auto fallback prefers claude when installed, otherwise opencode. Each provider auto-approves permissions in the worktree (the ticket worktree is the sandboxing boundary): Claude Code runs with --permission-mode bypassPermissions (override with AGENTIC_CLAUDE_PERMISSION_MODE=acceptEdits or skip for --dangerously-skip-permissions); opencode runs with --dangerously-skip-permissions (override with AGENTIC_OPENCODE_PERMISSION_MODE=interactive). When the resolved profile leaves model empty, opencode defaults to MiniMax-M3 (openrouter/minimax/minimax-m3); pass --model or set agent_model in the ticket's agent_meta to override per call.

Autonomous sprint loop (dev-loop / dev-monitor / dev-stop)

Where dev-auto drives one ticket, dev-loop drives the whole sprint unattended. It runs continuously, each cycle:

1. Advance — for every ticket with an open PR, check GitHub's review decision and check rollup. PRs marked changes requested are left for a human; the rest go through the same dev-finish gate (merges only when the local self-review approves and checks pass), which then tears down the worktree, flips Done, closes the issue, and unblocks dependents.
2. Refill — when no actionable Todo items remain, run plan-sprint to promote unblocked Backlog/Blocked items into Todo (disable with --no-promote).
3. Start — run the autopilot on every actionable Todo/In-Progress ticket (unblocked, not assigned to someone else, no existing PR) in parallel. The per-worktree run-lock prevents double-starts.
4. Idle — when a cycle merges/starts/promotes nothing, sleep --interval seconds (default 60) and re-check. Runs until Ctrl-C, dev-stop, or --once (single cycle, for cron).

dev-loop                       # 24/7 autonomous sprint runner
dev-loop --once --no-promote   # single cycle, don't auto-promote (cron-friendly)
dev-loop --interval 120 --merge-method squash --agent claude

Humans stay in charge of authoring backlog drafts/issues and of any PR the reviewer flagged with changes requested — the loop never force-merges those.

Observability

Every autopilot phase records {agent, model, duration, tokens, cost, turns} to <worktree>/.agent-context/auto/stats.json (per phase + totals) and appends structured events to events.ndjson (per ticket) and <solution>/.agentic-runtime/events.ndjson (run-level: run_started, issue_started, pr_opened, merged, needs_human, run_finished). Token/cost come from the agent CLI when it surfaces them (Claude Code's stream-json result event); other CLIs record duration only. These NDJSON streams are the stable contract for a future Grafana/Loki exporter — see templates/docs/observability-events.md.

Live monitor + emergency stop

Run dev-monitor in a second terminal for a live table — one row per in-flight ticket (phase, elapsed, tokens, $cost, PR state) with a totals footer (Σ tokens, Σ cost, Σ time, active/done/needs-human/failed). Non-TTY output is a single JSON snapshot (cron/CI friendly).

• In the monitor, press k then y for an emergency stop-all.
• Or from any terminal: dev-stop (raise the cooperative STOP flag + signal every running dev-loop) or dev-stop --kill (also terminate in-flight agent runs immediately).

Stops are graceful: the loop and autopilot halt at the next phase boundary, leaving worktrees and progress.json intact so a later dev-loop / dev-auto resumes from the recorded step. dev-loop clears a prior STOP flag when it starts.

Remote execution (server-*)

The sprint loop is most useful on an always-on box. Agentic Remote Development keeps planning local and sends execution to a 24/7 server — they coordinate through GitHub (already the source of truth) plus an optional Redis/Loki/Grafana stack on the server. The local CLI becomes a thin remote-control over SSH; the server runs the same agentic CLI inside tmux so you can SSH in and take over.

# one-time
server-add prod --host 1.2.3.4 --user agentic --remote-path /home/agentic/solutions/terminales
server-setup prod                 # idempotent bootstrap: git/gh/node/tmux/docker + agentic CLI
server-up prod                    # deploy + start redis/loki/promtail/grafana (ports bound to 127.0.0.1)

# drive it (planning stays local)
plan-draft && plan-promote        # local: create issues from local drafts/manifests
server-run prod -- dev loop       # remote: autonomous sprint loop in a detached tmux session
server-status prod                # in-flight tickets, phase, tokens, cost (over SSH)
server-logs prod                  # tail the remote run-event stream
server-tunnel prod                # open Grafana at http://localhost:3000 (SSH -L)

# intervene when the reviewer rejects a PR after the auto-fix attempts
dev-open --server prod 62         # open #62's worktree in a VS Code Remote-SSH window
dev-open --server prod 62 --shell # …or an SSH shell instead
server-ssh prod                   # → tmux attach -t agentic-loop  to watch live

Remote VS Code (Remote-SSH): dev-open --server <name> [issue] opens the worktree on the server in a VS Code Remote-SSH window (code --remote ssh-remote+<host> <path>) — a seamless editor on the 24/7 box; pass --shell for an SSH shell instead. Add an ~/.ssh/config Host alias to the server entry for clean key/identity handling: server-add prod … --ssh-host <alias> (then ssh/rsync/VS Code all use the alias). Requires the Remote-SSH extension in your local VS Code.

How it fits together

• Transport is SSH. server run <name> -- <args> runs agentic <args> on the server; long-running commands (dev loop, dev auto) start in a detached tmux session so the SSH call returns and a human can later tmux attach. No daemon, no queue.
• Servers live in ~/.config/agentic-workflow/servers.json (mirrors the solution registry): host, user, port, identityFile, remotePath, and a tunnel block of observability ports. --server defaults to the single server, else the configured default.
• Local vs remote split is natural: plan-draft/plan-promote operate on local drafts/manifests → run them local; plan-sprint/dev-loop/dev-auto need the board or compute → send them to a server. Both sides see the same GitHub Project, so nothing is shipped between machines for the core loop — the server has its own clone.
• Observability stack runs on the server, ports bound to 127.0.0.1; reach Grafana/ Prometheus/Loki/Redis from your laptop via server tunnel (SSH -L) — nothing is exposed to the internet. Promtail ships the NDJSON event streams + agent logs into Loki; a Prometheus exporter (agentic serve-metrics) turns GitHub board/PR state + Redis cost/jobs into real-time gauges. Grafana ships five provisioned dashboards (Board, Productivity, Financial, Infra, Alerts), each with a Sprint dropdown (multi-select, default All) that rescopes both Prometheus and Loki panels — Board adds assignee-load / phase-bottleneck / slowest-issue views, Productivity adds issues-by-author, and Financial adds per-issue/agent/provider cost+token tables. Unified alerting → Telegram covers PR (changes-requested/approved/merged/closed), sprint (promoted/none/completed), blocked, and per-provider cost-limit events, with tappable Open PR / Issue / Board links in each message. Set Telegram + monitoring.costLimits (and monitoring.boardUrl for the board link) in solution.yml before relying on alerts. See templates/docs/observability-events.md. Redis persists (appendonly) across restarts.
• Scales to more servers later. A stateStore abstraction backs coordination: with one server the file run-lock prevents double-starts; set remote.redisUrl (or AGENTIC_REDIS_URL) and the loop registers server heartbeats, fans out events, and uses an atomic Redis claim so two servers never grab the same issue — no code change, just config. For running the tool as a team (multiple Linux users sharing a server + Redis, per-user caps/providers, per-user metrics, and the path to a pool of servers / a future backend), see the multi-user RFC.

Setup: server setup runs the deterministic templates/infra/bootstrap.sh over SSH (installs git/gh/node/tmux/docker + the CLI; idempotent). For host-specific snags, server setup --prompt hands off the bundled agentic-remote-setup skill so an agent can finish the job. See templates/docs/observability-events.md for the event schema + Loki/Grafana wiring.

Token-efficient automation

A core goal of this CLI is to reduce unnecessary token usage when working with AI agents. Instead of asking agents to perform every task directly, the CLI delegates mechanical and repeatable operations to scripts. Agents focus on the work where they provide the most value:

• Reasoning, planning, implementation guidance
• Self-review and peer review
• Decision-making and trade-off explanations
• Improving issue quality

Scripts handle everything that doesn't require reasoning: worktree management, status flips, context collection, file scaffolding, clipboard handoff, PR opening, merge, archive. This separation makes the workflow efficient, predictable, and cost-effective.

Skills

The CLI ships a set of bundled skills under .github/skills/ (installed by agentic init and refreshed by agentic update):

• agentic-ideation — capturing raw ideas
• agentic-spec-writer — turning ideation into drafts + manifest rows
• agentic-planner-pipeline — driving the plan-* commands and the board
• agentic-dev-pipeline — driving the dev-* commands and the worktree
• agentic-self-review — authoring reviews/<branch>/... and pr-content.md
• agentic-pr-reviewer — peer-reviewing a PR via dev-review

Skills give agents the conventions, rubrics, and command map for this workflow so they can operate consistently across planning, development, and review tasks.

Command Overview

# Daily verbs (top level)
agentic start | auto | loop | review [--self] | pr | finish | commit | reset   # dev pipeline
agentic open | cd | list | monitor | stop                              # worktrees + control
agentic sprint | draft | promote | board                              # planning
agentic target [local|remote]                        # where execution verbs run

# Groups (less-common)
agentic dev <subcmd>     context | agent | remove | reset | release | open-mode
agentic plan <subcmd>    sync | roll-sprint | ready | deps | transition | todos
agentic server <subcmd>  add | run | ssh | logs | status | tunnel | setup | up | down | list | default
agentic serve-metrics                                # Prometheus exporter (board/PRs/cost/jobs)

# Setup / management
agentic init | update | solution <…> | project link | skills install | shell <install|uninstall>

Each subcommand has --help. With agentic target remote, the execution verbs (start/auto/loop/review/pr/finish/commit/stop) run on the default server automatically (--local to override); planning verbs always run locally.

For the full command + flag surface, see templates/docs/CHEATSHEET.md. For an end-to-end smoke test, see templates/docs/agentic-workflow-demo.md. For the long-form architecture, see templates/docs/agentic-workflow.md.

Workflow Summary

Requirements
    ↓
Ideation                    (skill: agentic-ideation → backlog/ideation/<slug>.md)
    ↓
Draft Issues                (skill: agentic-spec-writer → backlog/drafts/ + manifests/<batch>.tsv)
    ↓
Backlog upload              (plan-draft → GH Project + GH Issues + board/backlog/, status=BACKLOG)
    ↓
Sprint planning             (plan-sprint promotes Frontier-0 → Todo + Frontier-1 → Blocked,
                             based on agent_meta.blocked_by; plan-deps to inspect the graph)
    ↓
Ready for pickup            (plan-ready --group → safe parallel batches)
    ↓
dev-start                   (no arg → picker over the Project's Todo items, auto-checks
                             up to 5 dependency-free + unassigned tickets; batch runs
                             in parallel with a live per-ticket dashboard
                             (--open-code for one VS Code window per ticket);
                             worktree + .agent-context/ + Status=In Progress;
                             REFUSES if assigned to someone else OR any blocked_by issue
                             is still open — override with --force)
    ↓
Implementation              (in the worktree — manually, or agent-run via
                             dev-start --headless / --auto)
    ↓
dev-commit                  (agent groups changes into lint-clean commits;
                             --run for headless)
    ↓
dev-self-review             (clipboard handoff → reviews/<branch>/… + pr-content.md;
                             in --auto the prompt is fed to a fresh agent run,
                             with one fix iteration on findings)
    ↓
dev-pr                      (formats the repo, gates on ready_for_pr: true;
                             creates the PR directly (--draft / --web available);
                             Status=In Review; --publish-reviews in --auto posts
                             review summary + gist on the PR for human audit)
    ↓
Peer review                 (pr-agent action + dev-review <pr#>)
    ↓
dev-finish                  (merges PR + tears down worktree + branch;
                             Status=Done, archives .agent-context/, closes Issue,
                             auto-unblocks descendants — all inline, no sync step;
                             dev-remove tears down WITHOUT merging → Status=Todo/Backlog)
    ↓
dev-release                 (dev → main release PR, when applicable)

Philosophy

This tool is built on the idea that AI agents should not replace the development workflow — they should enhance it. Agents are most useful when given clear context, structured tasks, and well-defined responsibilities. This CLI provides that structure by combining:

• Human decision-making
• AI reasoning
• Scripted automation
• Reusable skills
• GitHub-based project management

The result is a development workflow that is easier to automate, easier to review, and easier to scale.

License

Copyright (c) 2026 Inspiracode. All rights reserved.

This software is proprietary and intended solely for use by Inspiracode and its authorized members and affiliates. See LICENSE for the full terms.