Imported from jasonneo99/agent-workflow (AGENTS.md). Install upstream with npx skills add jasonneo99/agent-workflow. Copyright stays with the author.

AGENTS.md

This repository is the shared Portable Agent Workflows kit. It defines reusable agents, automatic agents, workflows, policies, and project templates that can be used from Codex, Claude Code, Cursor, Aider, or any other agent-aware tool.

Project Context

• Reusable agent cards live in agents/**/*.yaml.
• Reusable workflows live in workflows/**/*.yaml.
• Project templates live in templates/project/.
• Runtime packages live in packages/.
• Developer-facing CLI lives in apps/cli/.
• Enterprise storage and local services live in infra/.

Repository-Wide Open-Source Boundary

The Open Source Boundary applies to every tracked file in this repository: source code, agent prompts, workflow definitions, schemas, migrations, tests, fixtures, documentation, screenshots, examples, configuration templates, and generated release metadata.

• Commit only portable framework behavior, generic contracts, synthetic or scrubbed evidence, and neutral examples.
• Never commit personal memory, real fleet topology, private project mappings, customer or product intelligence, credentials, machine-specific paths, or unsanitized runtime artifacts.
• Put personal assistant behavior, private skills, real host configuration, and deployment overlays in a separately access-controlled companion repository.
• A private companion may depend on tagged Agent Workflow releases; Agent Workflow must never depend on or import the private companion.
• Run npm run validate-boundary before committing. Do not weaken its checks to accommodate private material; generalize or move that material instead.

Agent Roster

Core agents:

• workflow-orchestrator: Workflow Orchestrator; routes natural-language goals, delegates to specialists, and owns final workflow coherence across registered projects.
• task-triager: classifies work and selects the right workflow.
• context-curator: keeps project context compact and current.

Development agents:

• technical-architect: plans implementation approaches.
• implementation-agent: performs scoped local edits and verification.
• frontend-engineer: handles frontend and UI implementation.
• backend-engineer: handles APIs, services, and jobs.
• database-engineer: handles schemas, migrations, and queries.
• test-engineer: adds and runs focused tests.
• ci-debugger: diagnoses failing checks and builds.
• security-reviewer: reviews auth, permissions, secrets, dependencies, and deployment risk.
• model-improvement-diagnostician: diagnoses whether quality or cost issues should be handled with context, prompts, routing, evals, retrieval, or fine tuning.
• eval-curator: turns approved feedback and failure patterns into scrubbed local evaluation cases.
• routing-optimizer: recommends provider, tier, fallback, and promotion changes from quality, latency, cost, and feedback evidence.

Product agents:

• product-strategist: turns goals and market constraints into product direction.
• ux-reviewer: Mira, the reusable UX/product-surface reviewer for workflow clarity, accessibility, polish, and trust.

Operations agents:

• docs-maintainer: updates docs, changelogs, and decision logs.
• pr-preparer: prepares PR summaries, review notes, and test evidence.
• release-manager: coordinates release readiness and go/no-go checks.

Automatic agents:

• auto-test-runner: runs configured verification.
• auto-docs-update: updates relevant docs after changes.
• auto-memory-summarizer: writes compact reusable memory from completed work.
• auto-ci-triage: watches CI and prepares targeted diagnosis.
• auto-release-check: checks release readiness.
• auto-wide-open-executor: runs trusted maximum-autonomy automation when explicitly enabled.

The local learning daemon also owns recurring repository hygiene and security maintenance. It may apply policy-allowed low/medium-risk source fixes when each changed file, before/after hash, risk decision, and validation result is written to the visible repository-maintenance receipt. High-risk trust-boundary changes still require explicit approval. It may create a local commit containing only its validated maintenance edits and must record the commit hash and message; pushing, publishing, merging, deploying, or rewriting history remains outside that authority.

Workflows

• build-feature: plan, implement, verify, document, and package a feature.
• review-pr: review changes for bugs, risks, missing tests, UX, and security.
• debug-failure: reproduce, diagnose, fix, and verify a failure.
• ci-triage: classify CI failures, diagnose the highest-impact issue, and verify the correction.
• security-audit: assess threats, secrets, dependencies, privacy, and remediation evidence.
• product-discovery: frame product problems, review experience needs, and assess feasibility.
• roadmap-curation: review daemon suggestions and insert only approved roadmap items without starting work.
• dependency-upgrade: assess, apply, and verify bounded dependency upgrades.
• data-migration: design, approve, execute, and verify reversible data migrations.
• performance-investigation: baseline, diagnose, optimize, and compare measurable performance.
• accessibility-review: audit accessibility barriers and verify remediation coverage.
• incident-response: triage, contain, verify recovery, and document follow-up work.
• architecture-decision: compare options and record an approved architecture decision.
• ship-release: check readiness and prepare release approval.
• maintain-context: refresh project context and reusable memory.
• model-improvement: diagnose and plan local quality, cost, routing, evaluation, retrieval, prompt, or fine-tuning improvements without exporting private data by default.
• wide-open-automation: run trusted automation with explicit maximum autonomy.

Autonomy

Autonomy is project-scoped. wide-open is allowed only when the project config sets:

policies:
  allow_wide_open: true

Even wide-open agents must write receipts for actions.

Commands

npm install
npm run validate
docker compose -f infra/docker-compose.yml up -d
npm run doctor
npm run migrate-storage
npm run bootstrap-storage
npm run index-project -- --project templates/project
npm run compile -- --workflow build-feature --project templates/project --task "..." --source-token-budget 3000 --source-max-files 20
npm run exec-command -- --project templates/project --run <workflow-run-id> -- npm run validate
npm run list
npm run compile -- --workflow build-feature --project templates/project --task "Add audit logging"
npm run worker -- --limit 6
npm run status
npm run artifacts -- --run <workflow-run-id>

Use DEFAULT_MODEL_PROVIDER=mock for deterministic local validation. Use DEFAULT_MODEL_PROVIDER=openai only when OPENAI_API_KEY is configured.

Worker-requested commands and file writes must pass .agent-workflow/project.yaml action policy before execution. File writes must be project-relative, allowed by allowed_write_paths, and recorded as receipts.

Use npm run init-project -- --project /path/to/project --profile enterprise for the default enterprise profile. Use --profile simple only when the user explicitly wants flat files without local services.

Working Rules

• Before write-capable work, acquire a project-scoped work intent with npm run reliability -- intent acquire; renew it while active and release it when finished. Interactive clients, daemon lanes, and workers must treat a conflicting intent as a stop condition rather than duplicating the work.
• Prefer changing YAML definitions over duplicating instructions in code.
• Keep agent prompts compact and role-specific.
• Keep workflow stages narrow and auditable.
• Treat project-local context as the source of truth for project-specific facts.
• Preserve portability across model providers.
• Apply the open-source/personal boundary to every file type and contribution, including tests and documentation.