0.0.22 • Published 2d agoCLI

@inspiracode/agentic-workflow

Licence

SEE LICENSE IN LICENSE

Version

0.0.22

Deps

Size

3.0 MB

Vulns

Weekly

Summary Dependency Versions

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 organized into two pipelines — agentic dev <…> (developer) and agentic plan <…> (planner) — plus a small flattened control plane that stays top-level: agentic loop|monitor|stop (the sprint runner, its live dashboard, and the emergency stop) and agentic board. shell install is the primary surface: it adds a catch-all a (→ a board, a dev pr) plus role-prefixed alias families — plan-* (plan-draft, plan-promote, plan-sprint, …) → agentic plan <…>, dev-* (dev-start, dev-auto, dev-review, …) → agentic dev <…>, monitor-* (monitor-up/down/status → agentic telemetry), todos/todo, bare loop / monitor, and an acd function (cd into a worktree, via agentic dev cd). 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:

AI agents for reasoning-heavy tasks: planning, implementation guidance, code review, decision-making.
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.
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, format, test, lint, envFiles extras — that file is the source of truth for which repos belong to the solution.

Per-repo secrets (envFiles). A repo folder may list untracked, secret-bearing files (default ['.env']) to ferry from your local clone into the running agent — without ever committing them:

{ "path": "../terminales-api", "role": "api", "repo": "inspiraCode/terminales-api",
  "envFiles": [".env"] }   // omit → defaults to ['.env']

docker provision copies each listed file from your dev clone into the server's main clone (then rsync over SSH), and dev start copies them from the main clone into every ticket worktree — necessary because a fresh git worktree has only tracked files, so a gitignored .env is otherwise absent where the agent runs. The files stay gitignored, so they never enter a diff. Use this for app/runtime secrets (DB URLs, API keys) that your app/test code loads via dotenv; MCP-server secrets are better carried in the per-user container env (users/<user>/.env).

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

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

One-command setup (`agentic setup`)

The fastest path from nothing to a running, multi-user, Docker-backed solution is the single guided command:

mkdir ~/solutions/my-product && cd ~/solutions/my-product
agentic setup my-product            # guided, resumable, Docker-first

agentic setup is a thin orchestrator over the building blocks below — it walks an ordered set of steps (solution → repos → board → agent CLIs → Docker transport → multi-user roster → build & start the stack → clone repos into per-user bind mounts → per-user auth → monitoring → verify), checkpointing progress to ~/.config/agentic-workflow/setup/<name>.json so it is resumable (agentic setup --resume) and re-runnable (agentic setup --reconfigure picks individual steps to replay). The Docker transport gives true multi-user out of the box: one shared observability stack (Redis/Loki/Grafana) plus one container per roster user, each with its own bind-mounted home/auth/repos/worktrees. Point the stack at the local daemon (--local) or a remote host via a docker context (--context ssh://…).

Tear a solution back down to a clean slate with agentic setup reset <name> (stops the Docker stack, removes the registry/server/checkpoint state; --volumes also drops the observability data, --purge-dir removes the solution directory — the GitHub Project and code-repo clones are always kept).

Or scaffold just the local solution skeleton (the step setup runs first):

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 plan 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)
Revising issue content after the fact with plan-update: edit a board/<status>/<n>-<slug>.md file (its  header is the issue title; everything after the header block is the body) and plan-update pushes the changed title/body to the GitHub Issue (idempotent — it skips when nothing differs). plan-update --pull does the reverse, refreshing the local file from GitHub (and hydrating the stub files seeded by plan-sync --pull), so the usual loop is pull → edit → push. Scoped to promoted real issues today.

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. `agentic agent` (configure runners / profiles / phases)

Configure the solution's agent config — runners (named {cli, model, provider?, effort?} tuples), profiles (fallback matrices of runner names), and the per-phase map. The fastest path is the guided wizard; nothing needs to be hand-edited. Built-in CLIs: claude, opencode, codex, gemini, qwen, cline, kilocode, pi, kimi (install with agentic cli install). The auto fallback prefers the first installed of claude → opencode → codex → ….

agentic agent setup                        # guided wizard: runners → profiles → phases → default
agentic agent models opencode              # list a CLI's models (live where supported, else catalog + docs)
agentic agent show                         # read-out (runners, profiles, phases, default)
agentic agent set --default standard       # set agents.default to a profile
agentic agent set --phase review=premium   # map a pipeline phase to a profile (repeatable)
agentic agent set --reset                  # clear agents.default (falls back to built-in `auto`)
# `dev agent` / `dev-agent` remain as back-compat aliases of show/set.

The wizard writes solution.yml; you can also edit it directly:

agents:
  runners:
    claude-opus:       { cli: claude, model: claude-opus-4-8, effort: high }
    codex-gpt5:        { cli: codex, model: gpt-5-codex, effort: high }
    opencode-deepseek: { cli: opencode, model: deepseek, provider: openrouter }   # → openrouter/deepseek
  profiles:                          # rows = fallback tiers (top→bottom); columns = interleaved per run
    premium:  [[codex-gpt5, claude-opus], [opencode-deepseek]]
    standard: [[claude-opus, codex-gpt5], [opencode-deepseek]]
    fast:     [[opencode-deepseek]]
    cheap:    [[opencode-deepseek]]
  phases: { implement: standard, commit: fast, review: standard, fix: standard, pr: cheap }
  default: standard                  # used for phases not listed in `phases`

A profile is a matrix: each row is a fallback tier tried top→bottom; the runners in a row are interleaved (round-robin per run) at the same priority, then fall through to the rest of the row before the next tier. The pipeline stops when every cell has failed. A matrix cell is a runner name (or a bare built-in CLI id used ad-hoc).

Thinking effort: a runner's optional effort (minimal | low | medium | high) is translated to the reasoning flag for codex, opencode, claude, and pi; other CLIs ignore it (with a one-time warning). Use higher effort for implement/review and lower for commit/pr.

Selection is layered (highest first): --profile <name> → --agent <id> (+ --model) → agent_meta.agent_profile → agent_meta.agent_cli → agents.phases[<phase>] → agents.default → built-in auto. An explicit --agent/agent_meta.agent_cli pins a single runner (no fallback); everything else resolves to a profile matrix. agentic solution current also prints the effective config.

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:

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).
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).
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 <pr#> --send       # post the existing (human-written/edited) review file to the PR
dev-review <pr#> --send --approve    # …and force the verdict (or --request-changes / --comment)
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.
--send (post a hand-authored review): the handoff path (no --run) leaves a reviews/<branch>/<date>-review-N.md file that an agent or a human wrote — but never posts it. dev-review <pr#> --send submits that latest review file to the PR as a formal GitHub review (same gist + summary + verdict mapping as --run), so a human can review in their editor, tweak the file, then send it. The verdict comes from the file's frontmatter by default; override it with --approve / --request-changes / --comment (at most one). It is idempotent (already-submitted revisions are skipped — pass --force to re-post after editing the file), honours --add-reviewer, and works across multiple PRs (dev-review 8 9 --send). --send and --run are mutually exclusive.

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.

Merged a PR outside the CLI? If a PR is merged directly on GitHub (the UI, or a manual gh pr merge), dev-finish never runs, so the board stays in In Review and the worktree lingers. agentic dev reconcile catches up: it scans the worktrees and, for each whose PR is MERGED but Status isn't Done, runs the finish path (flip Done, close the issue, unblock dependents, tear down the worktree). Pass an issue number (agentic dev reconcile 54) to reconcile just one. The autonomous loop already does this every advance cycle; the command is for a one-off when no loop is running.

Need to clean up an orphan, abandon, or restart a ticket worktree instead of finishing it? Use agentic dev remove:

agentic dev remove [<n>]            # tear down the worktree WITHOUT merging
                            # (Project Status left UNCHANGED by default)
                            # --requeue returns Status → Todo (so dev start re-picks it)
                            # --backlog returns Status → Backlog (implies --requeue)
                            # --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 by default leaves the Project Status unchanged — orphan cleanup for a ticket already done/closed elsewhere; pass --requeue to return it to Todo (or --backlog for Backlog). It also cleans up after a manual git worktree remove/rm -rf: run agentic dev remove <n> and it prunes the stale git metadata (re-queuing only with --requeue/--backlog).

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

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

Unlike agentic 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/):

Implement — the agent CLI runs with .agent-context/AGENT_PROMPT.md as its prompt, directly in the new worktree.
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).
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.
Sync base + Fix (one iteration) — before fixing, the base branch is merged into the worktree so the fixes (and the todos.tasks follow-ups the fix records) land on top of current base. 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.
Sync base + PR + human handoff — the base is merged once more so the PR is mergeable the moment it opens; 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.

Conflict avoidance + auto-resolution. Concurrent tickets used to collide on the shared todos.tasks file and block auto-merge. Two layers fix this: the repo's .gitattributes marks todos.tasks with the built-in union merge driver (git + GitHub keep both sides' appended lines — zero agent cost), and each base-sync above merges origin/<base> into the branch early. When a sync hits a real code conflict the union driver can't handle, the agentic-conflict-resolver agent (the resolve-conflicts phase) is handed the conflicted files, the base history since the branch point, the conflicting commits/PRs + their GitHub issues, and this ticket's issue + latest review, and resolves the merge; unresolvable conflicts abort the merge and flag a human (conflict_unresolved → Telegram alert). Run it by hand on any ticket — even in repos outside a solution — with agentic dev resolve [<n>|<pr-url>|<path>]. Peer review (dev-review) deliberately never syncs the base — it only reviews the PR head and posts a verdict; the PR's author owns fixing findings and syncing.

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.

Per-phase agents + provider fallback

The agents config (see dev-agent) drives this: each pipeline phase resolves to a profile matrix, which the autopilot flattens into an ordered chain of runners to try. If a run fails for any reason (non-zero exit — rate/quota limit, lost auth, network, error) it retries the same phase with the next runner in the matrix; the columns at one tier are interleaved (round-robin per run) for load distribution, and rows are strict fallback tiers. implement, commit, review, and fix each fall back independently; the pipeline stops a phase only when the whole matrix is exhausted. Every transition emits a provider_failed event (with a classified reason), a provider_fallback event when it switches runners, and provider_recovered when a fallback succeeds — so the monitoring stack can alert on provider trouble and on resumption (see observability-events.md). agentic dev agent --print shows the runners, profile matrices, and phase map.

Autonomous sprint loop (`loop` / `monitor` / `agentic stop`)

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

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. PRs that were merged outside the loop (e.g. via the GitHub UI) are reconciled the same way — flip Done, close the issue, unblock dependents, tear down the worktree — so a manual merge never leaves the board stuck in In Review.
Refill — when no actionable Todo items remain, run plan-sprint to promote unblocked Backlog/Blocked items into Todo (disable with --no-promote).
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.
Idle — when a cycle merges/starts/promotes nothing, sleep --interval seconds (default
1. and re-check. Runs until Ctrl-C, agentic stop, or --once (single cycle, for cron).

loop                       # 24/7 autonomous sprint runner
loop --once --no-promote   # single cycle, don't auto-promote (cron-friendly)
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 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: agentic stop (raise the cooperative STOP flag + signal every running loop) or agentic 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 loop / dev-auto resumes from the recorded step. 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/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 server 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
agentic-docs — using the solution docs/ knowledge base as durable agent memory
agentic-docs-capture — persisting in-chat decisions/corrections into docs/

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

Knowledge base (`agentic docs`)

Each solution can keep an AI-first knowledge base under docs/ — business rules, binding decisions, integrations, patterns, and live progress — written to be consumed by agents first and used as durable, shared memory so context need not be re-pasted each prompt. Human-only material (manuals) lives under docs/manuals/; everything else targets AI agents.

agentic docs init            # scaffold docs/ (non-destructive; --dry-run to preview, --force to overwrite)
agentic docs graph           # [experimental] graphify knowledge graph, if graphify is installed

docs init is non-destructive — it only adds missing files, so it safely extends a hand-built docs/. The knowledge base is committed deliberately with the solution repo (the CLI never auto-commits it). Keeping it current is the job of the two skills above (non-blocking — they nudge, they don't gate a PR): agentic-docs reads docs/AI_CONTEXT.md at session start, and agentic-docs-capture turns decisions made in chat into precise docs/ edits.

Slash commands (Claude Code)

Claude Code merged custom commands into skills: a <solution>/.claude/skills/<name>/SKILL.md becomes the /<name> slash command. The CLI installs a set of user-invoked commands that drive the agentic CLI for the mechanical work and use the AI agent to automate/validate the reasoning around it — more than thin wrappers:

Command	What it does
`/learn`	Update `docs/` from the cross-repo diff since docs were last updated + the current chat session
`/idea`	Capture a product idea into `backlog/ideation/`
`/draft`	Spec-write conventional draft ticket(s), then ask before uploading to the board
`/promote`	Promote drafts → GitHub issues (with a dry-run preview)
`/sync`	Reconcile the local board mirror with the GitHub Project
`/edit-ticket`	Edit an idea/draft/issue title+body and sync to the board
`/sprint`	Promote the unblocked dependency frontier into the sprint's Todo
`/status`	Read-only summary of in-flight work and what to pick next

They install into <solution>/.claude/skills/ (the only location Claude Code reads as / commands), alongside a mirror of the bundled agentic-* skills so Claude Code auto-discovers them too. agentic init and agentic update install/refresh them (skip with --no-commands); agentic skills install --claude does it standalone. The mechanical context for /learn comes from a new agentic docs changes helper — deterministic work in the CLI, reasoning in the skill.

Command Overview

# Control plane (top level)
agentic loop | monitor | stop                        # sprint runner + dashboard + e-stop
agentic board [init]                                 # the Project board view
agentic doctor                                       # full health check (config, repos, agents, remote + docker)
agentic target [local|remote]                        # where execution verbs run

# Developer pipeline
agentic dev <subcmd>   start | auto | review [--self] | pr | finish | commit | reset | resolve
                       reconcile | open | cd | list | context | agent | remove | release | open-mode

# Planner pipeline
agentic plan <subcmd>  draft | promote | sprint | sync | update | roll-sprint | ready | deps
                       transition | archive | assign | workload

# Knowledge base
agentic docs <subcmd>  init | changes | graph        # scaffold/maintain the solution docs/ KB

# Todos + remote + setup
agentic todos [add|remove]                           # todos.tasks follow-ups
agentic server <subcmd>  add | run | ssh | logs | status | tunnel | setup | up | down | list | default | metrics
agentic telemetry <up|down|status>                   # ship local telemetry to Grafana
agentic setup [name] | setup reset [name]            # one guided, resumable, Docker-first setup / teardown
agentic init | update | solution <…> | project link | skills install | shell <install|uninstall>

Each subcommand has --help. With agentic target remote, the execution verbs (loop, stop, and dev start/auto/review/pr/finish/commit/reset) 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;
                             agentic dev remove tears down WITHOUT merging → Status unchanged (--requeue → 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

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

Keywords

agentic ai-agents cli github-projects git-worktree developer-workflow ticket-pipeline