{
  "markdown": "# Lightstrator\n\n**English** · [Português (Brasil)](README.pt-BR.md)\n\nOrchestration harness for coding agents: instead of the main model going off\nreading and editing files on its own, it routes the work to specialized\nsub-agents that reply compressed. The main context lasts far longer in a long\nsession.\n\nWorks on **Claude Code** (native), **Codex CLI** and **Gemini CLI /\nAntigravity** (personas + context). Prompts are in English, but the activation\ntriggers are bilingual — requests in Portuguese are still routed, and the agent\nreplies in whichever language you write.\n\n## Installation\n\nThe [caveman](https://github.com/JuliusBrussee/caveman) plugin is a **required\nprerequisite** — install it first:\n\n```\n/plugin marketplace add JuliusBrussee/caveman\n/plugin install caveman@caveman\n```\n\nThen Lightstrator:\n\n```\n/plugin marketplace add Clevinacio/lightstrator\n/plugin install lightstrator@lightstrator\n```\n\nYou also need `jq` on your PATH. Details, optionals (`rtk`, statusline) and\ninstructions for other CLIs:\n[`docs/PREREQUISITES.md`](docs/PREREQUISITES.md).\n\n## What ships in the package\n\n### Sub-agents\n\n| Agent | Model | When it fires |\n| --- | --- | --- |\n| `investigator` | haiku | Understand where something is implemented or how a flow works, before acting |\n| `quick-fixer` | haiku | Small mechanical error: typo, import, lint, formatting, obvious syntax |\n| `code-reviewer` | sonnet | Review a diff before commit or merge |\n| `debugger` | sonnet | Bug, failing test, unexpected behavior — find the root cause |\n\nThey all reply in caveman's compressed style: only the result, no narrating the\nprocess. Code, paths, commands and error messages stay exact.\n\n### Skills\n\n| Skill | Role |\n| --- | --- |\n| `orchestrator` | Routing table: which situation goes to which sub-agent, and when **not** to delegate |\n| `brainstorming` | Turns an idea into a design through dialogue, one question at a time, before any code |\n| `writing-plans` | Writes the implementation plan from the approved design |\n\n### Hooks\n\nThree context injections: the orchestrator routing (on every prompt), the\nbrainstorming → writing-plans sequence (in plan mode only) and the execution\nhandoff (when a plan is approved, via `PostToolUse` on `ExitPlanMode`).\n\n### Optionals\n\n`optional/statusline-limit.sh` (5h and weekly limit usage in the statusline) and\n`optional/rules.md` (global rules that ship with the harness).\n\n## Main flow: plan mode → plan → execution\n\nThe path for any non-trivial work is always the same. Every arrow is guaranteed\nby a hook or a skill, not by the model's goodwill.\n\n```\nplan mode ──▶ brainstorming ──▶ writing-plans ──▶ ExitPlanMode ──▶ orchestrator\n   │              │                   │                │               │\n   hook       design through      plan with          user           execution\nplan-mode      dialogue         tasks and steps    approval        task by task\n```\n\n**1. Enter plan mode.** The hook injects the reminder: brainstorming before any\nplan.\n\n**2. `brainstorming`.** One question at a time until the design is settled. No\ncode before your approval.\n\n**3. `writing-plans`.** Writes the plan as small tasks, each with exact files,\ncode and a verification command. In plan mode the plan goes to the session's\nplan file; outside it, to `docs/superpowers/plans/`. The path is announced —\nexecution starts by reading that file.\n\n**4. You approve** via `ExitPlanMode`. The session drops to auto mode and the\n`PostToolUse` hook injects the handoff.\n\n**5. `orchestrator` executes.** One task at a time: reads the task, fetches\nmissing context with `investigator` (or skips it, if the plan already carried\nit), implements, sends mechanical fixes to `quick-fixer`, calls `debugger` when\na step fails unexpectedly, runs the verification, passes it through\n`code-reviewer`, ticks the checkbox and commits. Only then does it move on.\n\nIf a task does not match the real code, execution stops and asks you — the plan\nis not fixed silently.\n\n## Direct triggers, without plan mode\n\nThe orchestrator hook enters every prompt, so direct requests are routed too —\nyou do not need to plan to benefit from the harness.\n\n| You say | What happens |\n| --- | --- |\n| \"investigate how X works\" | `investigator` maps it and returns only the conclusion |\n| \"fix this typo / import\" | `quick-fixer` applies it |\n| \"review my diff\" | `code-reviewer`, one line per finding |\n| \"this test is failing\" | `debugger` finds the root cause before any fix |\n| \"implement X\" (clear scope) | `investigator` → implementation → `code-reviewer` |\n| \"implement X\" (new feature) | stops and suggests plan mode + `brainstorming` |\n\nThe triggers in the `description` fields are bilingual on purpose: the same\nphrases work in Portuguese (`\"corrige esse typo\"`, `\"revisa meu diff\"`).\n\nThe last row is the rule that avoids the worst case: discovering the design\nwhile writing the code. Signs that X is too big to go straight in — you do not\nknow which files change, there is more than one reasonable approach, or the\nrequest creates a subsystem. When in doubt, the orchestrator asks instead of\nguessing.\n\n**Fixing a bug, in detail:** `debugger` finds the root cause → a trivial fix\ngoes to `quick-fixer`, a fix with a design decision stays with the main agent →\n`code-reviewer` reviews before closing.\n\n## Development\n\nCanonical source (edit by hand): `agents/`, `skills/`, `hooks/`,\n`.claude-plugin/`, `package.json`.\n\nGenerated by `scripts/build.mjs` (do **not** edit): `AGENTS.md`, `GEMINI.md`,\n`gemini-extension.json`, `.codex-plugin/`, `.codex/`.\n\n```bash\nnpm run build     # regenerates the artifacts for the other CLIs\nnpm run check     # fails if anything is stale (runs in CI)\n```\n\nSee [`docs/PORTING.md`](docs/PORTING.md) for the per-CLI degradation matrix and\nhow to add a new target.\n\nWhen touching the `description` fields in `agents/*.md` or\n`skills/orchestrator/SKILL.md`, keep the triggers in both languages — CI fails\nif a Portuguese trigger disappears.\n\n## Credits and license\n\nMIT — see [`LICENSE`](LICENSE).\n\nThe `brainstorming` and `writing-plans` skills are derived from\n[superpowers](https://github.com/obra/superpowers) by Jesse Vincent, also under\nMIT. The modifications are documented in\n[`vendor/superpowers/UPSTREAM.md`](vendor/superpowers/UPSTREAM.md), and the full\nattribution is in [`NOTICE`](NOTICE).\n\n[caveman](https://github.com/JuliusBrussee/caveman) by Julius Brussee is a\ndependency, not redistributed here.\n",
  "bytes": 6437,
  "sha": "d2a91f80b8b050960df7837ae551c83c4da731d419933fa034bf12fcbbab833c",
  "repo_slug": "clevinacio/lightstrator",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_clevinacio_lightstrator_c6da499f/readme"
}