v26.11.3

This release installs devkit with one command, runs its
hooks from a pinned copy, gives you a live dashboard, puts the crew under one enforced RACI (who is Responsible,
Accountable, Consulted, and Informed for each kind of work), holds irreversible actions until you grant them, protects
devkit's own state from agents, carries a session's work through compaction, backs up branches that exist only on
this Mac when that starts no CI run, explains what fills your disk and frees it item by item, and makes the audit trail
verifiable and exportable.

What changes for you

devkit refuses more in this release. Each refusal says why and names the command to use instead.

• You run dev install, dev update, and install.sh yourself, in a terminal. Agents are refused them.
  dev install refuses a checkout with uncommitted tracked changes or code that does not compile, and pins only a
  published release or a commit whose bin/dev ci --run passed; --unverified --why "…" overrides that, and the
  override is audited.
• Agents cannot change devkit's state, configuration, or install. Writes to ~/.local/state/devkit,
  ~/.config/devkit/config.json, and ~/.local/share/devkit, dev config set safeguards.* or audit.*, and
  dev config edit are refused to every agent. You change safeguards in a terminal. A DEVKIT_* variable added to
  the env block of a Claude Code settings file (user, project, or local) is refused and removed.
• devkit cannot be pointed elsewhere by an agent. The guard refuses HOME, DEVKIT_CONFIG, DEV_ROOT, or
  DEVKIT_SESSION set for dev, and a swapped dev link or another dev earlier on the PATH. devkit reads a
  non-standard DEVKIT_CONFIG or DEV_ROOT only from a command you run in a terminal with no agent among its parent processes.
• Four escape hatches moved. dev commit, dev push, dev pr create, and dev release no longer read
  DEVKIT_SKIP_SECRET_SCAN or DEVKIT_LOCAL_CI_PASSED from their environment. Pass --ci-passed (recorded as
  attested), or let a real dev ci --run lift the push budget. dev git and dev gh no longer read
  DEVKIT_FLAKY or DEVKIT_CROSS_PROJECT from theirs; rerun a flaky CI run with
  dev run rerun <id> --flaky "<reason>". In the main session, a hatch still works as a prefix of the command
  itself, such as DEVKIT_SKIP_SECRET_SCAN=1 git commit, where the guard sees it and records it as guard.bypass;
  the next prompt names it, and DEVKIT_GUARD=off is recorded once per session and shown when a session starts.
• Irreversible actions wait for your grant. In the main session, these need a line you type on its own,
  grant <action> <target>: merging a pull request (grant merge 142), releasing a version, also by pushing its tag
  (grant release v26.11.3), a force push or a push to the default branch, a comment, review, or edit on a pull
  request or an issue, publishing a package, a deploy, a write through an API, and an MCP tool that sends, creates,
  or deletes something outside this Mac. The refusal names the exact line. A grant is used once, holds only in the
  repository of the session you typed it in, and expires after 30 minutes. A push of another branch and a new pull
  request are recorded, not held. For its first week on a Mac the gate only records what it would refuse, then it enforces;
  safeguards.irreversible_main sets it.
• Some actions are yours alone, in every setting. Lifting an embargo (dev branch embargo --lift),
  dev backup --public, and a change to a project's backup policy wait for a line you type: grant embargo <branch>
  or grant backup <project> (grant developer-only <target> works too). The gate's first audit week does not let
  them through, and crew members never run them.
• An agent's push or pull request of an embargoed branch needs your grant embargo <branch>. A push or pull
  request from a folder the guard can only learn when it runs (cd "$X" && git push, GIT_DIR=$G git push) is
  refused while any project on this Mac has an embargo; the agent writes the folder out instead.
• A decision is yours only in your own words. It counts when you answer the question dialog, or type a line of
  your own: approve D3, approve D3: B, or grant push feat/invoice-export. Without that, an answer the tech lead
  records is marked unverified, and an irreversible decision stays pending. dev crew mode auto --approve takes one
  target per action (push feat/*) and never pre-approves publish, deploy, a developer-only action, or a command the
  guard cannot name.
• Crew members are named by role. devkit's output, briefs, and refusals write a member as Backend engineer
  (Tank) and the main session as the tech lead. A final message or a member's report whose prose names a member
  without the role is sent back once; the role alone is fine, in any language (canary.roles).
• dev options are read exactly. Every dev command refuses an abbreviated option (--sched for
  --scheduled), and a word after -- is an argument, as the guard reads it.
• dev pr ready needs local CI evidence for HEAD, because marking a draft ready starts its one CI run. When every
  check of a pull request was skipped, dev pr checks reports no checks yet (exit code 8) and dev pr merge waits for
  the real run.
• Only the tech lead plans and decides. dev progress start, assign, begin, reopen, skip, and done, and
  dev crew decide and mode, are refused from a crew member and from a script. A second dev progress start on a
  live run needs --replace --why "…".
• The RACI is enforced. dev progress assign refuses a member who is not Responsible for the step's kind of work,
  and dev progress done refuses to end a run before each Accountable member approved; --why "…" overrides both
  and is recorded. dev progress start and add refuse unknown, ambiguous, or duplicate step names and dependency
  cycles, and no step starts before its dependencies are done.
• Crew members are held tighter. They are refused every escape hatch (DEVKIT_* variables, env -i,
  --ci-passed, --no-verify, dev config set, new secret-scan exceptions). A review or read-only member's shell
  runs only a read-only allowlist; add your project's own checks with safeguards.readonly_commands. Members never
  merge, release, tag, publish, deploy, write through an API, or force-push. A member pushes a branch, backs one up,
  or opens a pull request only in a step allowed it (dev progress assign --allow push,pr), and only with your grant
  for that action or a decision of yours that names it; the step keeps the target and the repository that evidence
  covers, and opens nothing else. When a review or read-only member's shell call writes files, the tech lead gets a
  message, which names the working member whose scope holds a file, and the member's step ends unverified until the
  tech lead checks the diff. In the session scratchpad, each member writes only in its own scratchpad/<member>/
  folder.
• A member's step ends done only on evidence. That is a Check ✓ in its report, or its own
  dev progress step --check. Otherwise the step shows as unverified, for the tech lead to close with evidence or
  reopen (dev progress reopen <step> --why "…").
• Approvals are explicit. Each finished step owes a verdict from the Accountable member of its kind of work,
  given after the work, for example by the Check ✓ of a review step that follows it. Nobody approves their own work:
  when the approver did it, the Code reviewer (Seraph) approves code and configuration, and the tech lead the rest. An
  approval needs the ✓ itself, so "tests not run" approves nothing, and a step with no approver cannot be approved
  until its kind of work is declared (dev progress assign … --activity <id>).
  dev progress step --approves "<steps>" and dev crew ask --decision --approves "<steps>" name the work a Check or
  your answer approves.
• Running a devkit hook by hand is refused in every session, because a hook event typed through a shell could
  forge your prompt or answer.
• Audit records are kept 13 months, on this Mac and in the handoff copy; this Mac used to keep two years.
  dev config validate refuses an audit.retention.floor_months under 3.
• dev ls, dev du, and dev status show what is on this Mac. A footer counts the other projects of the
  portfolio, and dev ls --all lists them with the dev clone command for each.
• dev gc is the old name of dev free. Without arguments it prints the plan to free space instead of a
  cleanup dry run, and dev gc 3 frees item 3 of that plan. dev gc --apply still runs the unattended cleanup.
• dev dashboard starts a local server and opens a one-time sign-in link instead of writing a file.
  dev dashboard --export <file> writes the static page.

Added

Install and update

• A one-line install: curl -fsSL https://raw.githubusercontent.com/fireflysoftwaresolutions/devkit/main/install.sh | bash
  installs Homebrew, git, Python, and the GitHub CLI when they are missing, clones the newest devkit release into
  ~/Development/fireflysoftwaresolutions/devkit, signs you in to GitHub, and starts the setup wizard. Its questions
  come from the terminal even through the pipe; without a terminal (CI), it runs without questions and says how to
  finish. It says first that devkit is for macOS (Apple Silicon and Intel) and stops on any other system. New:
  --no-setup, --help, and the DEVKIT_HOME, DEVKIT_REPO, and DEVKIT_REF variables. Each step says in one
  plain sentence what it does and why; a failed step is named, with the command to run again; and the run ends with
  what you have now and what to do first.
• A first install for people who are not developers: a step-by-step guide in Getting started, with what you
  see at each step. Pressin...

v26.11.2

Added

• A security policy (SECURITY.md) with private vulnerability reporting on GitHub, and a contributing guide
  (CONTRIBUTING.md), now that the repository is public.

Changed

• The release process in Developing devkit uses dev pr merge, dev release, and a check of the published archive.

Fixed

• dev agents test reads the hooks log from the byte offset it recorded, so the guard check no longer reports
  "no guard decision logged" when earlier lines hold multi-byte characters.
• dev ci --run --resume reruns the steps that read every file (secret, filesystem, and docs scans) after a
  docs-only change: a document can leak a key too. Builds and code linters still keep the docs shortcut.
• The Stop hook asks for dev plan revise only for the plans of the project the session works in. With two sessions
  open, it no longer sends one back over a plan the other changed in another project.
• dev doctor compares the installed instructions (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md) and the Codex crew
  roles with what this devkit writes, so an outdated install shows as out of date instead of passing because the
  files exist.
• The installed-plugin check compares the newest copy by version number, so 26.11.10 counts as newer than 26.11.2.

v26.11.1

devkit is open source under the Apache License 2.0.

Added

Testing

• dev test runs the tests that failed last time first, then only the tests your changes can affect (the blast
  radius), with pytest, unittest, Jest, Vitest, Maven, Gradle, Go, PHPUnit, or Pest. dev test run takes paths,
  --failed, --affected, or --all; dev test plan shows what would run and why; -p <project> works from
  anywhere. A selection that runs no test exits with 2 instead of passing.
• Tests that can fail. dev test audit finds tests that cannot fail for a real bug (no or trivial assertions,
  empty bodies, swallowed failures, skips without a reason, sleeps, mock-only and smoke-only tests) in Python,
  JavaScript and TypeScript, Java and Kotlin, Go, and PHP. dev test prove checks that each new test fails without
  your change and passes five times with it. The Stop hook sends back a development turn whose new or changed tests
  cannot fail.
• dev ci --run --resume repeats only the failed steps, the steps that never ran, and what the fix affects. Its
  evidence combines the full run with the affected tests, and the pull request says so.
• The testing skill: a test strategy per kind of code, TDD, flaky tests, mutation testing and diff coverage, and
  diagnosing an existing suite. Required whenever a turn writes or runs tests.

CI/CD

• dev ci audit diagnoses the pipelines of GitHub Actions, GitLab CI, Bitbucket Pipelines, and Azure Pipelines:
  security, reliability, speed, quality gates, and delivery, each finding with a severity and its fix, merged with
  actionlint, zizmor, and glab ci lint. --fix applies the safe GitHub fixes (permissions, auto-cancel, job
  timeouts, actions pinned by SHA) and prints the snippets for the other hosts; --strict fails on medium findings.
• dev ci init writes a pinned pipeline for the detected stack and host: lint, tests with a JUnit report,
  security scans, and on release tags an SBOM, signing or attestation, and a check of what was published. On GitHub
  it writes ci.yml, a cache-free release.yml, and dependabot.yml; GitLab signs keyless, Bitbucket and Azure with
  a cosign key.
• dev ci watch starts after every push and pull request, follows the runs to the end, reads the first error of
  a failure, sorts it into a class, and gives one next action. The main session gets it as a crew message and hands
  fixes that are not trivial to Link.
• The delivery-policy field job_timeout_minutes (default 30) sets the job timeout that dev ci audit suggests,
  --fix writes, and dev ci init generates; a generated test job runs the policy's test gate.
• The cicd skill: fast, reliable, DevSecOps pipelines on any host. Required whenever a turn changes a pipeline.
• devkit's own CI runs a security job (gitleaks, semgrep, osv-scanner, trivy, zizmor), and actionlint joins the
  security tools.

The crew

• 25 specialist agents named after The Matrix and led by the main session as Morpheus, from one roster
  (config/crew.json) for Claude Code, Claude Desktop, Codex (as roles), and the ChatGPT app. Each member has its own
  lane and time, the files it is assigned (the guard keeps its edits inside them), and a status block it must end its
  report with, which the SubagentStop hook checks (the crew canary). At most four members work at once.
• dev crew: the roster and who works now (show), briefs with the launch line (brief), routing (route),
  delegation (delegate, decline), the dispatcher (next), messages (ask, answer, inbox), decisions (mode,
  decide, decisions), and sync for the generated agents.
• Guided or automatic. In guided mode, decisions that are yours wait for you; in auto mode, the crew takes the
  recommended option and records it for review. Irreversible actions wait in both unless you pre-approved them.
• The crew skill: who to send for each kind of work, parallel or in sequence, briefs, and reports.

Progress

• Time you can trust. Active time (turns and subagents, never the wait for the developer), per-step estimates,
  dependencies (after), a critical-path ETA shown as a range, and a pace that one odd step cannot swing.
• A plan that stays true. Closing a step needs its evidence (--check) and a description that matches it;
  dev progress add, reopen, skip, history, and assign --scope; every change is recorded and audited.

Unfinished work

• Build it for real. dev stubs finds unfinished work in a change or a repository: TODO and FIXME markers,
  "not implemented" code, placeholders, and empty Python bodies. The Stop hook sends back a development turn that leaves
  untracked ones, and the guard refuses a commit that would include them. Planned work names its task (TODO(T-…)) or
  issue.
• The global rules: every test must be able to fail for a real bug; after a failure, re-run only the failed tests and
  what the fix affects; the full suite once, before the push; no stubs or placeholders in delivered work.

Surfaces

• Codex gets the plugin's slash commands as skills of the same name.
• New slash commands: /devkit:progress, /devkit:crew-status, /devkit:test, and /devkit:stubs.
• The Claude Desktop extension has 18 tools, among them devkit_crew, devkit_stubs, devkit_test_plan, and
  devkit_ci_audit.
• The dashboard's run card shows active time, the ETA range, the steps, and the crew's lanes.

Changed

• The handoff note stays current. After every development turn with new commits, the Stop hook asks for a note
  and task update when your commits are newer than the note's last real change (task and session lines written by
  devkit do not count). It also works for sessions that started outside the repository, such as Claude Desktop's.
• The scout is now Sparks, a member of the crew; scout remains an alias in Claude Code and Codex.
• The UI skills are required for design work only: "open the dashboard" no longer asks for them.

Fixed

• dev sec scan kept the leading dot of hidden paths in zizmor results: ./.github/workflows/ci.yml no longer
  becomes github/workflows/ci.yml.
• The crew canary counts only subagents someone launched. Claude Code's own helpers, such as the compaction
  summary, are no longer counted as crew misses or sent back, and a report corrected after the reminder is
  recorded as corrected.
• dev progress note sends an update while a step is still running, so no update has to close a step; the
  silence reminder and the global rules now ask for a note, not a step, until the step is finished.
• dev test prove <file> proves only the file's new or changed tests, so tests that already existed are no
  longer reported as not testing your change.

v26.11.0

The first release.

Added

Workspace and setup

• Workspace layout for any git host, with GitHub repositories in ~/Development/<owner>/<repo>, other hosts in
  ~/Development/<host>/<group>/<repo>, projects without a remote in _local/, managed worktrees in .worktrees/,
  and scratch files in .tmp/. dev clone, dev new, and dev adopt keep repositories in place.
• Setup wizard (dev setup, started by install.sh): it detects the Mac and both agents; asks for the workspace,
  the handoff repository (yours or a shared one), the agents and their permission modes, your stacks, your git hosts
  and clouds (preselected from what the Mac already shows), the Docker VM, automation, and the settings lock; shows
  the plan; installs only the packages you need; applies the configuration; offers the sign-ins; and runs
  dev doctor. In a terminal it is a full-screen wizard driven with the arrow keys, with Recommended setup (what
  it detected, straight to the review) or Customize, a review with the packages per group and Change a section,
  and an apply step with live progress and the fix for each failure. A second run starts from the saved choices and
  marks what would change. Pipes, TERM=dumb, and --yes keep the line prompts; --yes accepts every default.
• The dev home and banner: the hand-drawn devkit wordmark with the amber spark as the dot of its i, and the
  tagline "Every repo in its place. Every agent on the same page." (also in the README hero and the plugin
  descriptions). The home shows the current project in three lines, the workspace in one, and the items that need
  attention, grouped, each with its command. Headings are a bold title with a rule.
• Git hosts and clouds: the configuration keys hosts (GitHub, GitLab, Bitbucket, Azure DevOps) and clouds
  (AWS, Azure, Google Cloud, DigitalOcean, Kubernetes, and OpenTofu or Terraform) choose which CLIs devkit installs, from
  Brewfile groups of the same names, and dev doctor checks that each is installed and signed in, with local checks
  only.
• dev install, safe to run again, in steps: config, tools, cli, git, handoff, instructions,
  skills, claude, codex, docker, docs, and launchd. The tools step installs only the packages that are
  missing for your stacks, git hosts, and clouds (packages.auto). dev update pulls devkit and applies it again.
• dev doctor checks the toolchain, GitHub sign-in and git identity, the workspace and handoff repository, the
  instructions and skills, Claude Code and Codex (settings, hooks, hook trust, plugins, MCP servers, profile models),
  sign-in and quota, the devkit plugin and whether each agent's copy is current, required skills, project settings
  that switch devkit off, sessions that ran with devkit, Docker, automation, the status-block canary and free disk.
  Its Claude Desktop and ChatGPT app checks prove that the apps' bundled agents use the same configuration and
  plugins as the terminal.
• dev agents reports installation, sign-in, plan, and quota for both agents, and dev agents test runs a real
  session and checks the hooks, the guard, the status block, the global instructions, and the devkit skills from
  recorded evidence.
• Scheduled jobs (dev jobs): sync (hourly), sleep (03:30), gc (04:00), repair (every 6 hours), audit
  (05:00), doctor (Mondays 09:00), and lessons (Fridays 16:00) as launchd agents com.devkit.job.<name>, generated
  from the jobs configuration key. dev jobs show|run|logs|journal|set --every/--at/--weekly|enable|disable|install.
  Each run has a timeout, a log, a journal entry, and an audit record, and a failure sends a notification. Custom jobs
  run any dev command. dev doctor checks that every enabled job is loaded and its last run passed. The jobs replace
  the single com.devkit.sync agent, which dev install removes.
• Audit trail (dev audit): every changing dev command, guard refusal, blocked settings change, missed status
  block, handoff write and push, settings repair, cleanup, and job run, with secrets redacted, in
  ~/.local/state/devkit/audit/YYYY-MM.jsonl. The audit job publishes it daily to audit/<user>@<host>/ in the
  handoff repository (audit.publish); dev audit --team reads every machine's. Filters: --days, --action,
  --actor, --json.
• Docker on Colima (vz, Rosetta, virtiofs) with Compose, Buildx, and Testcontainers settings; dev docker.
• Git identity and credentials from the GitHub CLI, shared defaults, and a global ignore file for agent and
  security-tool output.

Handoff, initiatives, and teams

• Handoff repository (default <github-user>/handoff, private, or shared by a team): PROJECTS.md, TASKS.md,
  ACTIVITY.md, registry.json, one note per project with frontmatter (status, priority, milestone, due date, tags,
  progress), generated auto and task blocks, plans, and an operations log.
• Near-real-time sync: every commit, push, merge, tag, rebase, PR, and release (by an agent or a dev command),
  every task, plan, lesson, and policy change, and every session start queue a background sync; events within about
  15 seconds share one run of about 3 seconds. The Stop hook writes the session line, renews locks, and publishes
  presence every 2 minutes, and the sync job runs hourly. A rejected push is rebased and retried once; a failure is
  audited and shown under Needs attention until a push succeeds.
• The hierarchy portfolio → initiatives → projects → tasks, plans, and sessions, used by every command, the session
  context, the dashboard, and the reports.
• Initiatives (dev initiative new|add|rm|ls|show): cross-project goals with workstreams, cross-project tasks,
  decisions, risks, and progress that counts the initiative's items and linked member tasks. dev handoff-import
  adopts an older handoff repository from a staging folder; five were adopted this way during the rollout.
• Work items in items/<scope>/<ID>.md: one versioned file per task, feature, bug, or spike, with a changelog line
  and a commit for every change. dev task add (with --type, --now, --later, --priority, --due, --why,
  --done, --claim), start or claim, release, done, block --why, unblock, cancel, move, edit,
  link --to <initiative>, show, history, and delegate --to. -p and -i work before or after the verb.
• Locks across machines: dev task start takes an 8-hour lock and pushes it at once; other sessions are told
  not to work on the task; locks renew while a session works and expire when nobody renews them. Changes of scope need
  --why.
• Delegation: dev task delegate assigns a task to a teammate and writes the message to send, copied to the
  clipboard.
• Versioned plans (dev plan new --kind plan|spec|spike|bugfix|adr, revise --why, approve, supersede,
  ls): every change records a version, who, and why. The Stop hook asks for a revision when a plan changed without
  one.
• Session logs in sessions/<scope>/YYYY-MM.md (append-only), presence in presence/<user>@<host>.json, and
  merge rules in .gitattributes, so machines and developers do not conflict. dev team shows who is working on
  what. dev handoff --log adds a line.
• dev overview, dev standup and dev note set for the portfolio, the last days, and project metadata.

Progress, time, and communication

• dev progress start|step|block|done: live progress of agent work, with named steps, an ETA from the real pace,
  estimates calibrated from this project's history, updates published to the team, and desktop notifications when a
  run blocks or finishes or a long turn ends.
• dev time: turn lengths, estimate accuracy, subagent durations, and the slowest commands.
• dev report: a Markdown status report for the team or management, with health rules you can explain.
• Hooks that keep you informed. UserPromptSubmit answers "how is it going?" from real records, CI/CD pipelines
  included, and ignores background notifications. PostToolUse times slow commands and reminds a quiet agent after
  about 8 minutes. SubagentStart and SubagentStop track subagents.
• The communicating skill with templates for kickoff, progress, status, decisions, explanations, final and
  failure reports, pull request descriptions, squash-merge messages, review comments, delegation, and the structured
  formats of every record. Agents write in plain American English.

Status block

• Every final message starts with the [Firefly> DevKit] status block: a bold header with project, branch and
  task, then Done, Check (✓, ⚠, ✗ or –, with the evidence), Progress while a run is active, and Next.
• The rule applies to every turn, without exception: short answers, questions, status updates, replies during
  background work, and any language. The first turn stays a clean test of the instructions; a session that missed the
  block once gets a reminder in every later prompt, and replies corrected after a reminder are counted apart
  ("N corrected after a reminder" in dev doctor, dev overview, and PROJECTS.md).
• Nothing comes before the block: no verdict, correction, greeting, or comment on the last command before it;
  "lead with the point" applies below it, and a reply that waits for background work starts with it too. Every
  communicating template that can end a turn (kickoff, progress, status answer, decision, failure) starts with the
  block. dev progress step prints the block itself (Done, Check, Progress, Next, then the checklist), and its new
  --check "<evidence>" fills Check. The Stop hook says whether the block is missing or which line came before it.
• Results per surface: every session and status-block result records where it ran (terminal, Claude Desktop,
  the ChatGPT...