simplicio-sprint 1.2.13

Autonomous sprint-to-PR delivery agent. Reads Jira/Azure DevOps/GitHub tasks, delegates code edits to simplicio-cli, ships draft PRs with evidence.

SendSprint

Autonomous sprint-to-PR delivery: read Jira, Azure DevOps or GitHub Issues, map the work, delegate edits, collect evidence, open draft PRs.
Commands stay in English so they can be copied exactly.

English | Português | Español | 日本語 | 한국어 | 简体中文 | Italiano | Français | Русский | Polski | हिन्दी | العربية | עברית | Bahasa Melayu | Bahasa Indonesia

---

The short version

Autonomous sprint-to-PR delivery: read Jira, Azure DevOps or GitHub Issues, map the work, delegate edits, collect evidence, open draft PRs.

Project DNA

simplicio-sprint is where tasks stop being wishes and become delivery loops: cards, repo context, mapper artifacts, draft PRs, and human review. The original README made that workflow concrete, so the refreshed version keeps the conversion-focused top while restoring the step-by-step operating manual.

The new first screen is the doorway; the restored guide below is the workshop. This README should help a stranger understand the promise quickly and still give an operator enough depth to run, validate, and extend the project.

Quick Start

pip install -U simplicio-sprint
sendsprint plan-local --repo . --sprint readme-globalization --goal "Refresh README system" -t "README-001|Globalize README|Apply multilingual README standard|All language files exist"
sendsprint run github "*" --repo . --scope mine

What it does

• Owns the macro-plan while simplicio-cli owns the code edit.
• Refreshes mapper context before converting cards into specs.
• Collects validation and screen evidence instead of shipping blind changes.
• Keeps PRs as drafts so the human remains the approval gate.

Why this README is built to earn attention

• clear first-screen promise
• language links before installation
• badges and a visual hero for fast trust
• copy-ready quick start
• proof before long reference material
• star history for social proof

How it works

flowchart LR
  mapper["simplicio-mapper
repo context"] --> current["SendSprint
this project"]
  prompt["simplicio-prompt
reasoning runtime"] --> current
  current --> evidence["validated evidence
tests, docs, screenshots"]
  current --> sprint["simplicio-sprint
delivery loop"]

Proof and validation

• Delivery steps are represented as reports instead of one-off shell output.
• Git push uses bounded backoff and reuses existing branches safely.
• The package depends on the current Simplicio mapper, prompt and CLI floor.

Simplicio ecosystem

• simplicio-mapper supplies repo context before interpretation.
• simplicio-cli executes focused code tasks with verification.
• simplicio-prompt provides fan-out and consensus runtime patterns.
• simplicio-sprint turns cards into draft PR delivery loops.

Documentation standard

• docs/cross-repo-issues.md
• docs/readme-globalization-standard.md

Original Field Guide

The section below restores the project-specific README material that existed before the globalization pass. Keep this substance when refreshing the top-level narrative: add polish, do not erase operational memory.

🇺🇸 English. Leia em português: README.pt-BR.md.

SendSprint is an autonomous agent that finishes the cards assigned to you. It reads your sprint from Jira, Azure DevOps or GitHub Issues, rewrites each card into the simplicio-mapper spec format, hands the actual code edit to simplicio-cli, captures test + screen evidence, commits on an isolated branch, and opens a draft pull request with the evidence attached. Then it watches the PR and feeds your review comments back to simplicio until you approve.

You don't sit at the keyboard invoking it. A scheduled trigger runs it; your only job is to review the draft PR.

Contents

• The split that makes it work
• The full pipeline
• Demonstration: a frontend card, end to end
• Install
• Configure credentials
• How to invoke it
• Watch mode (the listener)
• The simplicio-mapper specs
• The 600-subagent fan-out
• Keeping the tools current
• Install the skill into your IDE / agent
• Logging — capture every step
• Architecture
• Environment variables
• Command reference
• FAQ
• Tests · License

The split that makes it work

• SendSprint = the agent (the brain). It owns the flow start to finish: read → map → execute → evidence → commit → PR → update ticket → review loop.
• simplicio-cli = the executor (the hands). Stateless. It runs one task → applied diff. It knows nothing about sprints, branches or PRs.

This separation is the whole idea: the brain never writes code, and the hands never make decisions. Each can be tested and swapped independently.

The full pipeline

trigger (cron / GitHub Action / Claude web)   ← removes you from the loop
  └─ SendSprint (agent)
       0. update tools       latest simplicio-cli / -prompt / -mapper (per profile)
       1. read sprint        Jira / Azure DevOps / GitHub Issues   (mcp → api, --scope mine)
       2. map each card      → .specs/... plus project-map + precedent context
       2b. (optional) fan-out brainstorm via YOOL/TUPLE/HAMT lazy subagents
       3. simplicio task ... ← the only thing simplicio-cli does (one task → diff)
       3b. collect evidence  tests + Playwright screenshot
       4. commit + push      isolated git worktree, bounded backoff
       5. open DRAFT PR      ← your only review surface
       6. attach evidence    test results + screenshots + manifest
       7. update the ticket  "In Review" + PR link
       8. watch the PR       review comment? → simplicio revises → re-evidence
            ✓ you approve → merge → next card

   …and every step above is written to a log file (see Logging).

Demonstration: a frontend card, end to end

A committed simulation proves the whole pipeline for a frontend card, without needing live credentials or a browser in CI: tests/test_e2e_frontend_sim.py.

pytest tests/test_e2e_frontend_sim.py -q

The card "WEB-7 — Add a Login button to the homepage header" arrives from Jira over MCP, and the test walks every stage:

1. Collect the task from Jira (MCP transport) → a Sprint with the card.
2. Map it into .specs/sprints/sprint-42/01-add-a-login-button…task.md (acceptance criteria become AC-1, AC-2).
3. Execute — the simulated edit adds the button to index.html (<a href="/login"><button>Login</button></a>), exactly as simplicio applies a diff.
4. Evidence — run tests and capture a screenshot committed under .sendsprint/evidence/WEB-7/screen.png.
5. PR — open a draft pull request with the evidence embedded.

The captured "print" of the delivered screen:

…and the evidence comment SendSprint posts on the PR:

## SendSprint evidence

### Steps
- [x] execute
- [x] evidence
- [x] commit

### Tests & screens
- ✅ **unit**: pytest — exit 0
- ✅ **screenshot**: homepage

  ![homepage](https://raw.githubusercontent.com/acme/web/feature/web-7/.sendsprint/evidence/WEB-7/screen.png)

The committed test uses a tiny injected PNG so it runs anywhere; with Playwright installed (pip install -e ".[screenshot]" && playwright install chromium) the real flow captures a true screenshot of the running screen — that's how the image above was produced.

Install

# 1) SendSprint itself (published on PyPI as `simplicio-sprint`)
#    This also pulls the current simplicio-cli / -mapper / -prompt packages.
pip install simplicio-sprint

# 2) optional: Playwright screen evidence
pip install "simplicio-sprint[screenshot]" && playwright install chromium

# 3) optional but recommended: pull the latest of every external tool
#    (also installs the simplicio-prompt kernel used by --fanout)
sendsprint update

Working on the agent itself? Clone the repo and pip install -e ".[dev]" instead.

Requirements: Python ≥ 3.11 and git. sendsprint update additionally needs git on PATH to clone the simplicio-prompt / simplicio-mapper helpers.

Configure credentials

Credentials are read from the OS keyring (via sendsprint login) or from environment variables. You only need the source(s) you actually use.

# one-time keyring storage
sendsprint login jira           # prompts for email + API token
sendsprint login azuredevops    # prompts for organization + PAT
# GitHub uses the GITHUB_TOKEN environment variable — no keyring entry needed

Or via environment variables — see Environment variables.

How to invoke it

There are two ways: directly via the CLI, or by asking an AI agent (Claude Code, Codex, Cursor, …) that has the SendSprint skill installed.

A) Directly, via the CLI

# Jira sprint 42
sendsprint run jira 42 --repo . --repo-slug owner/repo --scope mine

# Azure DevOps iteration (note the escaped backslash)
sendsprint run azuredevops "Team\\Sprint 12" --repo . --repo-slug repoId

# GitHub milestone #7 (or "*" for all open issues assigned to you)
sendsprint run github 7 --repo . --repo-slug owner/repo --scope mine

What the arguments mean:

Argument	Meaning
<source>	jira | azuredevops | github
<sprint>	Jira sprint id, ADO iteration path, or GitHub milestone (* = all open)
--repo	path to the target git repository
--repo-slug	owner/repo (GitHub) or repository id (Azure DevOps) — used for the PR
--scope mine	deliver only the cards assigned to you (all for the whole sprint)
--base	the PR target branch (default develop)
--fanout	run the 600-subagent brainstorm per card (opt-in)
--no-specs	skip writing the simplicio-mapper .specs/ file
-o report.json	write the full run report as JSON

B) By asking an AI agent

If the skill is installed (see Install the skill), the host assistant never reimplements the flow — it shells out to the sendsprint CLI. These phrases trigger it:

• 🇧🇷 "rode o sendsprint", "executar sprint", "entregar sprint"
• 🇺🇸 "run sendsprint", "ship my sprint", "deliver my sprint"
• 🇪🇸 "ejecutar sprint"
• the slash command /sendsprint
• or simply naming a sprint id + source + repo together

When your MCP servers (Atlassian / Azure DevOps / GitHub) are available, the agent registers them so the operators read live tenant state over MCP; otherwise the operators fall back to the REST API automatically.

Watch mode (the listener)

Watch mode is how SendSprint runs without you at the keyboard. It polls the source, delivers the cards you haven't delivered yet, and remembers what it already shipped so it never duplicates work.

# one pass and exit — this is what a cron / GitHub Action / scheduled trigger calls
sendsprint watch jira 42 --repo . --repo-slug owner/repo --once

# stay alive and run a pass every 15 minutes (Ctrl-C to stop)
sendsprint watch jira 42 --repo . --repo-slug owner/repo --interval 15

# at most N cards per cycle (default 1 — small, reviewable PRs)
sendsprint watch github "*" --repo . --repo-slug owner/repo --once --max-per-cycle 3

How it behaves:

• It always scopes to your cards (--scope mine).
• Delivered card keys are recorded in .sendsprint/runs/watch-state.json; the next pass skips them. Delete that file to re-deliver.
• --once does a single cycle and exits with a non-zero code if any step failed (ideal for CI). Without --once it loops forever, one cycle per --interval minutes, and keeps running even if a cycle fails (the error is logged).
• Each delivered card still stops at a draft PR — watch mode never merges.

Schedule it

Run sendsprint watch ... --once from:

• a GitHub Action on a schedule — see .github/workflows/sendsprint.yml;
• a cron job;
• a Claude Code on the web scheduled trigger (docs).

You can also keep an eye on the PR after it's open: an agent subscribed to PR activity reacts to review comments by running the review loop (below).

The simplicio-mapper specs

Before handing a card to simplicio-cli, SendSprint writes it into the simplicio-mapper format inside the worktree, so the executor has rich, structured context:

.specs/sprints/
├── BACKLOG.md
└── sprint-XX/
    ├── SPRINT.md
    └── NN-slug.task.md     # frontmatter + Acceptance Criteria, Test plan, Definition of Done

Each task file carries the card's title, description, acceptance criteria (parsed into AC-1, AC-2, …), labels and ticket link. Turn it off with --no-specs.

When the target repo already has mapper artifacts, SendSprint also reads .simplicio/project-map.json and .simplicio/precedent-index.json. It ranks relevant files, recent changes, architecture signals and precedent snippets for the current card, embeds them under ## Structured mapper context, and passes that same compact context to simplicio-cli.

Real-stack evidence sprints

SendSprint treats Playwright + web + API + PostgreSQL/local database goals as analysis-first sprint work. Use plan-local for these ad-hoc efforts, then let the generated mapper specs drive the concrete execution slices:

sendsprint plan-local \
  --repo /path/to/repo \
  --sprint real-stack-evidence \
  --name "Real-stack evidence" \
  --goal "Use Playwright to prove web screens against API and local Postgres" \
  --task "REAL-STACK-EVIDENCE|Prove web screens|Run mapper endpoint checks, start real services, execute focused Playwright specs, and document artifacts."

The helper generate_real_stack_evidence_task() produces this standard task shape programmatically for planner integrations.

The 600-subagent fan-out

Optionally, before implementing a card, SendSprint can fan the task out across hundreds of real subagents via simplicio-prompt to brainstorm edge cases and a plan, then folds the result into the simplicio task. When SIMPLICIO_PROMPT_REPO points at a current simplicio-prompt checkout, SendSprint uses the YOOL/TUPLE/HAMT PromptFanout adapter and lazy batch_spawn receipts instead of enumerating workers. The older SIMPLICIO_PROMPT_KERNEL subprocess path remains as a fallback.

# 600 subagents per card (needs the kernel + a provider key)
sendsprint run jira 42 --repo . --repo-slug owner/repo --fanout

# offline cost preview — no API key, no network
sendsprint run jira 42 --repo . --repo-slug owner/repo --fanout --fanout-dry-run

It is opt-in and degrades gracefully: with no tuple adapter, kernel or key it logs a skipped step and continues. sendsprint update installs the prompt checkout and points SIMPLICIO_PROMPT_KERNEL at the legacy kernel automatically.

Keeping the tools current

sendsprint update pulls the latest of every moving part:

sendsprint update                 # all three
sendsprint update --no-mapper     # skip simplicio-mapper

Tool	How it updates
simplicio-cli	pip install -U simplicio-cli
simplicio-prompt	git clone/pull into the cache, sets SIMPLICIO_PROMPT_KERNEL
simplicio-mapper	git clone/pull into the cache

run and watch also refresh tools at start, driven by your runtime profile (~/.config/sendsprint/profile.yaml). Skip it per-run with --no-update, or globally with SENDSPRINT_NO_UPDATE=1.

Install the skill into your IDE / agent

sendsprint install writes the SendSprint skill into each agent's own convention, from a single source, so the trigger phrases work everywhere.

sendsprint install --all                 # every supported agent
sendsprint install -t cursor -t claude    # just these
sendsprint install --all --repo /path/to/project

Agent	Where the skill is written
Claude Code	.claude/skills/sendsprint/SKILL.md
Cursor	.cursor/rules/sendsprint.mdc
Kiro	.kiro/steering/sendsprint.md
Gemini	GEMINI.md (managed block)
Codex / OpenCode / Antigravity	AGENTS.md (managed block)
Hermes / openclaw	AGENTS.md (managed block — fallback)

Shared files (AGENTS.md, GEMINI.md) get an idempotent managed block between markers, so re-running never clobbers your existing content.

Logging — capture every step

Every command configures the sendsprint logger to a rotating log file (full DEBUG detail) plus the console. The log records each delivery step, every simplicio / fan-out invocation, transport choices and errors.

# global options (before the subcommand)
sendsprint --log-level DEBUG run jira 42 --repo . --repo-slug owner/repo
sendsprint --log-json --log-file ./run.jsonl run github "*" --repo .

• Default location: ~/.local/state/sendsprint/logs/sendsprint.log (override with SENDSPRINT_LOG_DIR).
• --log-json writes one JSON object per line (easy to ingest).
• run also archives the full RunReport JSON next to the logs (run-<timestamp>.report.json).

Architecture

sendsprint/
├── operators/      task readers: JiraOperator, AzureDevopsOperator, GitHubIssuesOperator (mcp|api)
│   └── _mcp_bridge.py  host-injected MCP seam (register_provider → fetch)
├── executor/       task → applied diff
│   ├── jsonpatch.py    JsonPatchExecutor — deterministic, zero-token fast path (sendsprint.json-patch/v1)
│   └── simplicio.py    SimplicioExecutor — the LLM boundary to simplicio-cli
├── mapper/         MapperAdapter — .specs/ tasks + project-map/precedent context
├── prompt/         PromptFanout — simplicio-prompt YOOL/TUPLE/HAMT fan-out
├── delivery/       worktree, git_ops, evidence manifest, PR create/review
├── models/         Sprint, SprintItem, StepReport, RunReport, ScopeConfig (Pydantic v2)
├── llm/            LlmClient — provider-agnostic completion client (pooled httpx)
├── tech/           detect_tech — repo stack fingerprint (front/back/infra)
├── utils/          LruTtlCache, TemplateRenderer, orjson helpers
├── workspace/      multi-repo workspace.yaml loader
├── core.py         sprint-plan validator (Rust kernel + Python fallback)
├── github_integration.py  ReviewReader (PR feedback) + evidence comment posting + CI
├── scope.py        --scope mine filtering
├── credentials.py  OS-keyring credential storage (sendsprint login/logout)
├── profile.py      ~/.config/sendsprint profile + defaults
├── progress.py     ProgressEvent stream for the live run table
├── state.py        RunState — graceful cancel + --resume
├── bootstrap.py    sendsprint update (pull latest tools) + start-up checks
├── installer.py    sendsprint install (write the skill per agent)
├── logging_setup.py  central logging (file + console, JSON optional)
├── flow.py         the orchestrator (read → map → simplicio → evidence → PR → review loop)
├── watch.py        the unattended trigger
└── cli.py          Typer CLI: run, watch, plan-local, update, install, login, logout, version

Environment variables

Variable	For
JIRA_BASE_URL, JIRA_EMAIL, JIRA_API_TOKEN	Jira
AZURE_DEVOPS_ORG, AZURE_DEVOPS_PROJECT, AZURE_DEVOPS_PAT	Azure DevOps
GITHUB_TOKEN, GITHUB_REPO	GitHub Issues + PRs
SIMPLICIO_MODEL, SIMPLICIO_BASE_URL, SIMPLICIO_TEST_CMD	simplicio-cli
SIMPLICIO_PROMPT_REPO	path to a simplicio-prompt checkout with examples/python/prompt_fanout.py
SIMPLICIO_PROMPT_KERNEL	path to the fan-out kernel (auto-set by sendsprint update)
SENDSPRINT_CACHE_DIR	where git-cloned tools live (default ~/.cache/sendsprint)
SENDSPRINT_LOG_DIR	where logs live (default ~/.local/state/sendsprint/logs)
SENDSPRINT_NO_UPDATE	set to 1 to skip the start-up tool update
SENDSPRINT_CONFIG_DIR	profile location (default ~/.config/sendsprint)
SENDSPRINT_EVIDENCE_VIDEO	set to 1 to render delivery videos without --evidence-video
HYPERFRAMES_CLI	explicit hyperframes command (else npx --no-install hyperframes)
SENDSPRINT_USE_RUST_CORE	set to 0 to force the Python sprint-plan validator (default: use Rust when installed)

Delivery videos (optional)

When a card ships UI and a screenshot is captured, SendSprint can render a short delivery video as extra PR evidence using hyperframes. It is opt-in:

sendsprint run github 12 --repo . --frontend-url http://localhost:4200 --evidence-video

• Enable per run with --evidence-video (on both run and watch) or globally with SENDSPRINT_EVIDENCE_VIDEO=1.
• The command is discovered from HYPERFRAMES_CLI, or falls back to npx --no-install hyperframes (needs Node + the hyperframes package).
• Output lands at .sendsprint/evidence/<KEY>/delivery-<KEY>.mp4 and is recorded in the evidence manifest.
• Missing binary is non-fatal: the step is reported as skipped (not failed) and the batch continues, so a run never breaks just because hyperframes is absent.

Command reference

Command	What it does
sendsprint run <source> <sprint>	deliver a sprint: each card → simplicio → evidence → draft PR
sendsprint watch <source> <sprint>	unattended trigger; --once for cron/CI, else loops
sendsprint plan-local	materialize an ad-hoc local sprint (--task KEY|Title|Desc) into .specs/
sendsprint update	pull latest simplicio-cli / -prompt / -mapper
sendsprint install --all	write the skill into every supported agent
sendsprint login <provider>	store credentials in the OS keyring
sendsprint logout <provider> <account>	remove a stored credential
sendsprint version	print the version

run and watch accept --evidence-video to render a delivery video — see Delivery videos.

Global options (before the subcommand): --log-level, --log-file, --log-json.

FAQ

Do I need simplicio-cli installed? For real code edits, yes (pip install simplicio-cli). Without it, the execute step is reported as skipped and no diff is produced — the rest of the flow still runs so you can see the wiring.

What if I have no Jira/ADO/GitHub MCP server? No problem. Transport is auto: it tries MCP first (when the host registers a provider) and falls back to the REST API. Set the REST credentials and you're fine.

Does it ever merge or push to my main branch? No. It pushes the work to an isolated branch and opens a draft PR. You review and merge. Watch mode is the same — it always stops at the draft PR.

Will it touch files outside the task? The executor is constrained to "touch only what the task requires; keep tests green". The mapper only ever writes under .specs/. The skill installer only writes its dedicated files or a marked block in AGENTS.md/GEMINI.md.

Is the 600-subagent fan-out required? No — it's opt-in (--fanout) and skips gracefully without a kernel/key. Use --fanout-dry-run to preview cost offline.

A reviewer left a comment — what happens? The review loop deduplicates actionable feedback, includes file/line context, re-runs simplicio to address it, re-collects fresh evidence, writes an evidence manifest, and pushes — repeating until you approve. An agent subscribed to PR activity can drive this automatically.

Where do I see what happened? In the log file (~/.local/state/sendsprint/logs/sendsprint.log) and the archived RunReport JSON. Use --log-level DEBUG for full detail.

How do I re-deliver a card watch already shipped? Delete its key from (or remove) .sendsprint/runs/watch-state.json.

Tests

pip install -e ".[dev]"
pytest tests/ -q
ruff check sendsprint/ && ruff format sendsprint/

Contributing & security

• CONTRIBUTING.md — dev loop, the Definition of Done, and the draft-PR-first workflow.
• SECURITY.md — how to report a vulnerability privately and which versions are supported.

License

MIT — see LICENSE.

Star History

License

MIT. See LICENSE.