CLI-Agnostic Agent Workflow

A portable agent workflow system for software feature development, compatible with Claude Code, Codex, OpenCode, and Kilo without locking into any vendor-specific folder as source of truth.

The source of truth is:

• AGENTS.md — persistent repo-level instructions
• .agents/skills/**/SKILL.md — reusable workflow skills
• .agents/agents/*.yaml — canonical agent definitions
• scripts/*.sh — validation and runtime materialization

The folders .claude/, .codex/, .opencode/, .kilo/, and .kilocode/ are runtime outputs or compatibility shims, not the primary editing surface.

What this repo provides

• Phase-based workflow: from idea to issue, plan, implementation, and validation
• Reusable skills, not just CLI-specific slash commands
• Canonical agents/analyzers with portable schema
• Native adapter generation per CLI
• Guided agent creation
• Skill creation, evaluation, and self-improvement
• MCP server building guide
• Local issue tracking (no GitHub API required)

Architecture

AGENTS.md                          # Portable persistent instructions
.agents/
  README.md                        # Canonical layer guide
  skills/                          # Canonical skills
  agents/                          # Canonical agents in YAML
  templates/                       # Reusable templates
scripts/
  validate-cli-agnostic.sh         # Validates the canonical contract
  sync-skills.sh                   # Materializes skills for runtimes that need it
  sync-agents.sh                   # Generates native agents per runtime
  scaffold-agent.sh                # Creates canonical YAML from JSON
  clean-generated.sh               # Deletes non-canonical generated outputs
.claude/                           # Compatibility and legacy UX for Claude Code
docs/CLI_AGNOSTIC_PLAN.md          # Context and decisions behind the migration

CLI compatibility

CLI	Instructions	Skills	Agents
Claude Code	.claude/CLAUDE.md → @../AGENTS.md	materialized copy in .claude/skills/	.claude/agents/*.md
Codex	AGENTS.md	reads .agents/skills/ natively	.codex/agents/*.toml
OpenCode	AGENTS.md	reads .agents/skills/ natively	.opencode/agents/*.md
Kilo	AGENTS.md	materialized copy in .kilocode/skills/	.kilo/agents/*.md

Notes:

• Codex and OpenCode read .agents/skills/ directly.
• Claude Code and Kilo require skill materialization via sync-skills.sh.
• Agents are always generated from .agents/agents/*.yaml.
• "CLI-agnostic" means shared source of truth + runtime adapters, not byte-identical behavior across clients.

Prerequisites

Minimum:

• bash
• python3
• Python yaml / PyYAML module
• git

Optional depending on the workflow:

• gh for GitHub workflows
• MCP Azure DevOps for Azure DevOps planning

Quick start

1. Validate the canonical layer

bash ./scripts/validate-cli-agnostic.sh

2. Materialize runtime outputs

bash ./scripts/sync-skills.sh --materialize all
bash ./scripts/sync-agents.sh --materialize all

3. Full refresh

bash ./scripts/validate-cli-agnostic.sh
bash ./scripts/sync-skills.sh --materialize all
bash ./scripts/sync-agents.sh --materialize all

4. Clean generated outputs

bash ./scripts/clean-generated.sh

This removes .codex/, .opencode/, .kilo/, and .kilocode/. .claude/ is kept because it is tracked as a compatibility layer.

Core workflow

The recommended development workflow moves through distinct phases. Each phase has a dedicated skill.

Phase 0 — General project docs

Before starting feature work, ensure the project has its foundational documentation under doc/general/:

• ARCHITECTURE.md — system design and key decisions
• API.md — API endpoints reference
• DEVELOPMENT.md — local development workflow and commands
• DEPLOYMENT.md — deployment guide

These files give the agent enough context to plan and implement without guessing. If they do not exist, create them before using the feature workflow.

Phase 1 — Explore the repo and decide which experts are needed

Before creating any agents, explore the codebase to understand its architecture and identify which analysis domains are genuinely relevant to your project. Not every project needs every possible analyzer.

Ask the agent to explore the repo and answer:

• What is the architecture pattern? (hexagonal, layered, monolith, microservices...)
• What is the tech stack? (framework, ORM, queue system, storage...)
• What are the main domain boundaries?
• What testing strategy is already in place?
• Are there external integrations (APIs, async jobs, auth systems...)?

Based on the answers, decide the minimum set of expert analyzers the project actually needs. Examples:

Project type	Likely needed experts
REST API with hexagonal architecture	api-contract, hexagonal-backend, testing-coverage
Full-stack with React frontend	react-frontend, api-contract, testing-coverage
Data-heavy backend	data-flow, database, testing-coverage
Multi-tenant SaaS	auth-multitenancy, api-contract, security, testing-coverage

Only create the analyzers that match your project. You can always add more later.

Phase 2 — Create sub-agents for the project

Use the create-agent skill to scaffold each analyzer identified in Phase 1. These are analysis-only agents: they read code and write findings to doc/features/<issue>/, they never modify application code.

skill: create-agent

The canonical agent schema lives in .agents/agents/. The skill generates runtime adapters automatically via sync-agents.sh.

Phase 3 — Create the issue

Use create-new-local-issue to define and capture the work. The skill clarifies requirements, drafts the issue, and waits for approval before writing the artifact. No GitHub API is called.

skill: create-new-local-issue

The issue is saved locally as a structured artifact. Review it carefully before proceeding. Respond to any clarifying questions the skill asks — the quality of the plan depends on the quality of the issue.

Phase 4 — Plan the issue

Use start-planning-local-issue to analyze the issue, invoke the relevant analyzers in parallel, and produce a detailed implementation plan at doc/features/<issue_title>/PLAN.md.

skill: start-planning-local-issue

The analyzers write findings to doc/features/<issue_title>/ before the plan is assembled. Review the generated plan closely. Check that:

• scope is correct and nothing unrelated slipped in
• the analyzer findings are accurate
• the implementation approach matches your architecture
• edge cases and risks are addressed

Ask follow-up questions or request adjustments before moving on. A bad plan produces bad code.

Phase 5 — Implement

Use start-working-on-local-issue to execute the plan. The skill runs tests continuously and reports completion status with local artifacts.

skill: start-working-on-local-issue

The agent commits frequently as it works. Track progress through the todo list it maintains.

Phase 6 — Validate

Use validate-local-issue-with-tests to independently verify the implementation against the issue need, the plan, and the Validation Contract. This skill writes honest tests and checks that the code has not drifted from the original requirement.

skill: validate-local-issue-with-tests

Use chatchup at any point to catch up on what has changed in the current branch compared to main.

skill: chatchup

Available skills

Core feature workflow

Skill	Description
create-new-local-issue	Clarifies requirements, drafts, and saves a local issue artifact
start-planning-local-issue	Runs analyzers and writes doc/features/<issue>/PLAN.md
start-working-on-local-issue	Executes the plan, runs tests, commits progress
validate-local-issue-with-tests	Validates implementation with honest tests against the issue and plan
chatchup	Reads all changes in current branch vs main

System building

Skill	Description
create-agent	Creates a canonical agent YAML and generates runtime adapters
skill-creator	Creates, evaluates, and improves skills; benchmarks with variance analysis
structured-user-questions	Reusable protocol for blocking clarification questions

Specialized

Skill	Description
mcp-builder	Guide to build MCP servers in Python (FastMCP) or Node/TypeScript

Canonical agents

Analyzer agents live in .agents/agents/ and are analysis-only. They write findings to doc/features/<issue>/ and never modify application code.

This repo ships only the template and one reference example (api-contract-analyzer). You are expected to create agents tailored to your project's architecture using the create-agent skill or by copying the template.

The base template is .agents/agents/agent-template.yaml.

Creating or editing a skill

Canonical location:

.agents/skills/<skill-name>/SKILL.md

Manual flow:

mkdir -p .agents/skills/<skill-name>
cp .agents/templates/skill-template.md .agents/skills/<skill-name>/SKILL.md
bash ./scripts/validate-cli-agnostic.sh
bash ./scripts/sync-skills.sh --materialize all

For guided creation, use the skill-creator skill.

Creating or editing an agent

Canonical location:

.agents/agents/<agent-name>.yaml

Options:

cp .agents/agents/agent-template.yaml .agents/agents/<agent-name>.yaml
# or
bash ./scripts/scaffold-agent.sh /path/to/spec.json

Then:

bash ./scripts/validate-cli-agnostic.sh
bash ./scripts/sync-agents.sh --materialize all

For the guided flow, use the create-agent skill.

What the validator checks

scripts/validate-cli-agnostic.sh verifies:

• required keys in each canonical agent
• no model key at root
• model_policy.default: inherit
• valid portability.level
• compatibility block for each runtime
• SKILL.md present in each skill folder
• structured-user-questions skill exists

It validates the canonical contract, not end-to-end runtime behavior in every CLI.

What to read for each case

• Understanding the repo: .agents/README.md
• Why this architecture exists: docs/CLI_AGNOSTIC_PLAN.md
• Changing persistent project rules: AGENTS.md
• Changing workflows: .agents/skills/**/SKILL.md
• Changing analyzers/agents: .agents/agents/*.yaml

Claude Code compatibility

The repo keeps .claude/ for compatibility:

• .claude/CLAUDE.md is a shim pointing to AGENTS.md
• .claude/commands/ preserves slash command UX
• .claude/skills/ is a materialized copy of the canonical skills
• .claude/agents/ are derived adapters

If you work exclusively with Claude Code, this still works. If you edit the system, edit .agents/, not .claude/.

References

• .agents/README.md
• AGENTS.md
• docs/CLI_AGNOSTIC_PLAN.md
• scripts/validate-cli-agnostic.sh
• scripts/sync-skills.sh
• scripts/sync-agents.sh
• scripts/scaffold-agent.sh
• scripts/clean-generated.sh