development-companion1.4.1

Development Companion

One installable development process for AI coding agents: 12 roles, 18 skills, and a CLI that adapts the same canonical base to OpenCode, Claude Code, Codex, Pi, and other harnesses.

npx development-companion@latest init

devcomp init detects the repository and harness, installs the process, and leaves your existing AGENTS.md and CLAUDE.md intact unless you choose otherwise.

Run devcomp doctor from the repository opened by the agent. If you work in a nested repository, install there too: its own AGENTS.md and agent configuration may take precedence. init --yes preserves existing rules; doctor fails when those rules do not activate the process. Ask the harness agent to merge existing rules, or use init --rules handoff for a backed-up, explicitly pending merge. --rules append remains available for compatible rules.

Why

Coding agents are powerful but inconsistent. Each harness has its own rules file, skill format, and subagent mechanism. Copying prompts between them creates drift: one harness gets the latest review checklist, another keeps an outdated one.

Development Companion separates the process from the harness:

Layer	Responsibility
Process	Discovery, architecture, security, QA, UX, delivery, deployment, closure.
Roles	Who decides, who delivers, and who verifies.
Skills	How each discipline is executed, with evidence.
CLI	Detects, installs, adapts, and diagnoses.

The same canonical content is installed everywhere. Adapters only translate paths and formats.

Install

New or existing repository

npx development-companion@latest init
# or
npm create development-companion@latest

Useful flags:

npx development-companion init . \
  --harness opencode \
  --profile web \
  --rules append \
  --branching trunk-based \
  --docs local \
  --memory engram

Flag	Effect
--harness <name>	Force the adapter; auto detects it.
--profile <name>	web, backend, mobile, desktop, cross-platform, full.
--skills <a,b>	Add specific skills.
--rules keep|append|handoff|replace	Policy for existing rules; handoff backs up AGENTS.md for agent-led merge.
--branching <name>	gitflow, gitlab-flow, trunk-based, github-flow, custom.
--docs local|tracked	Keep design docs local or version them in docs/companion/.
--memory engram|none	Recommend Engram for cross-session memory.
--mode copy|symlink	How skills are installed.
--dry-run	Print the plan without writing.
--yes	Non-interactive; rules default to keep.

Rules are never overwritten silently

If AGENTS.md or CLAUDE.md already exists, the CLI asks:

• keep — leave the file untouched;
• append — add a managed block, preserving your rules;
• handoff — back up AGENTS.md under .companion/local/rules-backup/, write a pending-merge notice and the process block; doctor fails until an agent merges project-specific rules and removes the notice. Existing CLAUDE.md is kept.
• replace — replace the file, with explicit confirmation and a local backup; AGENTS.md still requires a reviewed merge of the original before work begins.

The managed block is delimited by <!-- development-companion:start --> and <!-- development-companion:end -->, so updates are idempotent.

Commands

Command	Purpose
devcomp init [dir]	Install the process, skills, roles, rules, and manifest.
devcomp add <skill|role|profile> <name>	Add content to an existing install.
devcomp scaffold [dir]	Generate the TypeScript reference monorepo.
devcomp doctor [dir]	Check skills, roles, rules, branching, and Engram.
devcomp update [dir]	Refresh installed content without overwriting local edits.

The process

The process exists to ship working software, not to produce documents. It is a loop:

0 Bootstrap
  → 1 Frame (one page, 30–60 min)
  → 2 Walking skeleton (end-to-end, fakes allowed)
  → 3 Slice loop (build → test → demo → next)
  → 4 Verify (security + QA, continuous)
  → 5 Release
  → 6 Close

Planning artifacts are living notes written just in time, not phase gates. The first commit lands before the second design document. See core/process.md and the incremental-delivery skill.

For a small change, the process collapses to the workflow in core/workflow.md.

Roles

Role	Primary question
Team Lead	What is the shortest path to a verified delivery?
Architect	What boundaries and trade-offs make this correct and evolvable?
Cybersecurity Engineer	What can be attacked, and what evidence proves the control works?
QA Engineer	How could this fail, and what proves it does not?
Frontend Engineer	Is the interface accessible, fast, and maintainable?
Backend Engineer	Are the API, data, and failure modes correct and secure?
Mobile Engineer	Does it respect the device, store, and offline reality?
Desktop Windows Engineer	Does it install, integrate, and update natively on Windows?
Desktop macOS Engineer	Is it sandboxed, signed, and notarized correctly?
Desktop Linux Engineer	Does it respect distributions, Wayland/X11, and packaging?
Multiplatform Engineer	Is the core shared and the edge adapted per platform?
SRE Engineer	Is it deployed, observable, and recoverable?

Role contracts live in core/roles/. The CLI installs them to .companion/roles/ and generates native bindings where the harness supports subagents. The canonical principles, process, workflow, quality gates, and guidelines are installed in .companion/core/. The generated rules and agent bindings reference these files.

Orchestration in OpenCode

devcomp init preserves OpenCode's native Build default and any existing OpenCode config. The native primary follows the Team Lead delivery contract from AGENTS.md and retains its harness skills, shell, edit and delegation tools. team-lead and the 11 specialists are callable subagents; invoke the dedicated lead for substantial coordination, not every routine slice. Its own binding denies edits outside local design notes and denies shell. devcomp doctor fails on the old default_agent: "team-lead" and primary-only binding: review local customizations, update the binding explicitly, remove that default (or select build), and start a new session. The CLI will not overwrite existing config or bindings.

Working modes

Mode	Primary agent	Use
Solo (default)	native Build	One agent implements, tests, and commits. Specialists are optional reviews.
Orchestrated	native Build + callable team-lead	The lead coordinates several specialists and verifies their evidence.
Legacy (do not use)	team-lead as primary	A read-only lead blocks direct implementation and confuses the workflow.

Migrating a legacy install (1.3.0 or earlier):

1. Review local customizations and make a private backup outside the repository of AGENTS.md, CLAUDE.md, .companion/core/, .companion/roles/, .agents/skills/, .opencode/agents/ and existing OpenCode configuration. Do not publish the backup or read/copy .env files.
2. npx development-companion@1.4.1 update <project> (without --force). This refreshes the managed rules block while keeping existing skills, core documents, roles and bindings. Review the rules diff; merge any customized managed-block instructions from the backup. Compare preserved content with 1.4.1 and merge needed updates manually rather than replacing all customizations.
3. In the existing opencode.json/opencode.jsonc at the project root or in .opencode/, remove "default_agent": "team-lead" or set it to "build", preserving other settings.
4. If .opencode/agents/team-lead.md still says mode: primary, review its backup and regenerate only that binding and role: npx development-companion@1.4.1 add role team-lead --target <project> --force. Reapply compatible customizations from the backup; keep mode: subagent and the coordination permissions. This targeted command overwrites both files without backup.
5. Start a new OpenCode session (the current one keeps the old agent).
6. npx development-companion@1.4.1 doctor <project> must show PASS default agent and PASS delivery mode.

Do not use a blanket update --force as a migration shortcut: it deletes installed skill directories and replaces roles, core documents and bindings, including local customizations. doctor checks the managed process block; separately review any project-specific instructions outside it for conflicts.

Why: a primary team-lead cannot edit code or run shell, so every change must be delegated. That is correct for orchestration and wrong for solo implementation.

Skills and profiles

Process skills are installed always:

project-discovery, architecture-design, test-strategy, ux-design, delivery-orchestration, security-review, deployment-sre, development-workflow, incremental-delivery, code-review.

Domain skills are installed by profile:

Profile	Skills
web	frontend, backend
backend	backend
mobile	mobile, frontend
desktop	desktop + Windows/macOS/Linux
cross-platform	multiplatform, desktop, frontend
full	all domain skills

Every skill is self-contained and follows the Agent Skills specification.

For UI design the agent offers local HTML/SVG, an existing Figma MCP, or FigCraft CLI if available. The CLI does not install third-party tools or handle Figma tokens. The ux-design skill explains how to find the official FigCraft CLI download, create editable files and exercise a clickable prototype in Play before approving the design.

Harness support

Tier	Harnesses	Commitment
1	OpenCode, Claude Code, Codex, Pi	Installation targets; behavioral validation required per release
2	Cursor, Gemini CLI, Copilot CLI, Windsurf, Cline	Best-effort, generated
3	Any harness that reads AGENTS.md or accepts a prompt pack	Generic fallback

Adapters are data: rules file, skills directory, agent directory, and limitations. Installation checks do not prove that a model followed the workflow. Claude Code and Codex provide specialist bindings but do not automatically start in a team-lead role; invoke it explicitly when orchestration is needed. Pi has no native subagents and must run the role workflow in one session or through a user-supplied extension. Validate real agent behavior in each harness before claiming process compliance.

Local design documents

By default, discovery, architecture, test plans, evidence, and reports live in .companion/local/, which is ignored by git. The manifest, installed core documents, roles, and skills can be tracked; the design notes remain local unless opted in.

If you want the design to travel with the repository:

npx development-companion init . --docs tracked

That moves the artifacts to docs/companion/.

This configured path overrides default .companion/local/ examples in role and skill files.

Memory: Engram (optional)

The process works without memory. If Engram is available, it stores decisions, findings, and session summaries between sessions. devcomp doctor detects it and prints the setup steps for your harness. The files remain the source of truth.

Security rules built in

• Never read .env values. Only key names and presence checks.
• Evidence per finding: file and snippet, command and output, request, CVE, or screenshot.
• No secrets in the repository, logs, screenshots, or reports.
• Least privilege for subagents; read-only reviewers where the harness allows it.
• UI reviewed with screenshots at desktop and mobile widths, using a vision-capable model.

Scaffold

devcomp scaffold generates a TypeScript reference monorepo:

• apps/web: React + Vite;
• apps/api: Node + Fastify;
• packages/domain, application, contracts;
• PostgreSQL in Docker;
• Vitest and Playwright;
• a runnable walking skeleton, not business logic.

The domain has no framework or infrastructure imports. Ports and adapters keep the implementation replaceable.

Develop this package

npm test
npm run pack:check
node bin/devcomp.mjs --help

Requirements: Node >= 22. No runtime dependencies, no postinstall, no telemetry.

End-to-end framework test

The expense tracker is a repeatable E2E fixture for the framework itself:

DC_E2E_ITERATION=01 node scripts/e2e-expense.mjs

It deletes ~/repos/dc-e2e-expense, installs the published package with npx, runs init, doctor, and scaffold, copies the expense app, and runs unit, API, component, and Playwright tests. Screenshots, command logs, process artifacts, and report.md are written to plannification/validation/e2e-expense/<iteration>/ (gitignored). The workdir stays for inspection; the next run deletes it.

This exercises installation and a prebuilt app fixture; it does not launch a coding agent or prove it followed instructions. Behavioral validation requires separate agent sessions.

Repository layout

bin/            CLI entrypoint
src/            CLI implementation
core/           principles, process, quality gates, roles, guidelines
skills/         Agent Skills
templates/      rules and artifact templates
adapters/       harness metadata and guides
test/           CLI tests

License

MIT. See LICENSE.