agentic-dev-workflows

Agentic Developer Workflows

A provider-neutral library for maintaining reusable AI-assisted software-development workflows across Codex, Claude Code, Cursor, and MCP clients. Canonical definitions live under core/; deterministic generators render provider-native assets, while validation and snapshot checks prevent those outputs from drifting from their source.

What It Provides

• Canonical workflows covering repository setup, safe changes, testing, reviews, documentation, releases, and visual design.
• Deterministic validation for workflow, command, agent, template, and link contracts.
• Generated Codex, Claude Code, and Cursor adapters with checked-in, drift-tested provider assets.
• A local, read-only MCP server for workflow discovery, rendering, validation, and repository health scoring.
• Reproducible provider-installation and repository-guidance examples.

Status

v0.1.0 defines the initial stable release. The planned implementation through Phase 9 is complete: the library generates Codex skills, agents, and commands; Claude Code skills and subagents; and Cursor rules and commands from the same provider-neutral core. A local, read-only MCP server exposes five structured tools for discovery, rendering, validation, and repository health scoring. Reproducible installation examples and release archives exercise the generated assets without becoming a second source of workflow behavior. The generic adapter remains deferred.

Use the Library

• Start with the unified installation guide for release archives, checksums, provider layouts, and MCP setup.
• Browse the canonical specifications in the core library.
• Install generated Codex assets with the Codex installation guide.
• Install generated Claude Code assets with the Claude Code installation guide.
• Install generated Cursor assets with the Cursor installation guide.
• Install and configure the local server with the MCP workflow server guide.
• Review installed snapshots and sample repository guidance in the Phase 8 examples.

Repository Layout

core/       Canonical provider-neutral workflows, agents, commands, and schemas
providers/  Thin provider-specific adapters derived from the core
mcp/        Local MCP servers that expose shared repository logic
examples/   Reproducible installations and illustrative repository guides
docs/       Architecture and contributor documentation

See the architecture overview for dependency rules and the rendering model. Repository-specific guidance for coding agents is in AGENTS.md.

See the provider adapter guide before regenerating or changing provider packaging.

Release Preparation

The v0.1.0 release notes describe compatibility, artifacts, verification, and known limitations. See the changelog for the release inventory and the roadmap for post-v0.1.0 plans.

Build the four deterministic ZIP files and their SHA-256 manifest locally:

python3 -B scripts/build_release.py --version 0.1.0

Generated files are written to the ignored dist/ directory. Tagging and publishing remain separate, explicit release operations.

Design Principles

• Keep canonical behavior provider-neutral.
• Prefer small, composable workflows over broad prompts.
• Make safety constraints and verification steps explicit.
• Produce readable summaries of actions, results, and remaining risks.
• Design scripts and tools for deterministic, agent-friendly use.

Verification

Python 3.11 or newer is required for the complete validation and MCP workflow. Run the same checks used by CI from the repository root:

python3 -B -m unittest discover -s tests -v
python3 -B scripts/validate_workflows.py
python3 -B scripts/generate_provider_assets.py --check
python3 -B scripts/generate_examples.py --check
git diff --check

The MCP protocol integration test runs when the MCP server package is installed.

License

Licensed under the Apache License 2.0.