{"id":50567929,"url":"https://github.com/franklioxygen/agent-workflows","last_synced_at":"2026-06-04T16:01:23.274Z","repository":{"id":360530966,"uuid":"1250508847","full_name":"franklioxygen/agent-workflows","owner":"franklioxygen","description":"Engineering workflows for AI coding agents or flesh engineers.","archived":false,"fork":false,"pushed_at":"2026-05-26T19:18:53.000Z","size":156,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-26T21:14:04.138Z","etag":null,"topics":["ai-agents","ai-workflows","development-guidelines","prompt-engineering","prompt-workflow","workflow"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/franklioxygen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-26T17:47:50.000Z","updated_at":"2026-05-26T20:19:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/franklioxygen/agent-workflows","commit_stats":null,"previous_names":["franklioxygen/agent-workflows"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/franklioxygen/agent-workflows","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/franklioxygen%2Fagent-workflows","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/franklioxygen%2Fagent-workflows/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/franklioxygen%2Fagent-workflows/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/franklioxygen%2Fagent-workflows/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/franklioxygen","download_url":"https://codeload.github.com/franklioxygen/agent-workflows/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/franklioxygen%2Fagent-workflows/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33912343,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-04T02:00:06.755Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ai-workflows","development-guidelines","prompt-engineering","prompt-workflow","workflow"],"created_at":"2026-06-04T16:01:22.136Z","updated_at":"2026-06-04T16:01:23.254Z","avatar_url":"https://github.com/franklioxygen.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\nFunction Name: README\nDescription: Public root README for the agent-workflows library.\n--\u003e\n\n# Agent Workflows\n\nLanguage: **English** | [简体中文](zh-cn/README.md)\n\nReusable engineering workflows for AI coding agents.\n\n`agent-workflows` helps agents choose the right process for project initialization, feature work, bug fixes, code review, incident response, refactoring, and tech debt cleanup. The library separates workflow-specific guidance from shared safety, preflight, and validation conventions so the docs stay reusable and easier to maintain, while adding checkpoints that help absorb silent base-model quality drift.\n\n\u003cp align=\"center\"\u003e\n    \u003cimg width=\"400\" height=\"400\" alt=\"EC6BFAEE-1138-4B0E-B6AB-23A17A72F38A\" src=\"https://github.com/user-attachments/assets/b243f0ae-4758-48c4-bdaa-7f133a9cfd5b\" /\u003e\n\u003c/p\u003e\n\n\nNew to the library? Start with [how-to-use-agent-workflows.md](how-to-use-agent-workflows.md).\n\n## Quick Start\n\nChoose one workflow and follow it directly:\n\n- New project or greenfield codebase: [project-initialization-agent-workflow.md](project-initialization-agent-workflow.md)\n- New feature or product behavior change: [feature-development-agent-workflow.md](feature-development-agent-workflow.md)\n- Existing behavior is broken: [bug-fix-agent-workflow.md](bug-fix-agent-workflow.md)\n- Review a PR, branch, or diff: [code-review-agent-workflow.md](code-review-agent-workflow.md)\n- Production incident or post-incident debugging: [incident-debugging-agent-workflow.md](incident-debugging-agent-workflow.md)\n- Behavior-preserving structural improvement: [refactoring-agent-workflow.md](refactoring-agent-workflow.md)\n- Cleanup, dependency upgrades, or debt survey: [tech-debt-cleanup-agent-workflow.md](tech-debt-cleanup-agent-workflow.md)\n\nManual usage example:\n\n```text\nUse the bug-fix workflow in bug-fix-agent-workflow.md for this issue:\n\n\u003cbug report\u003e\n```\n\nAutomation usage example:\n\n```text\nUse $workflow-automation to select the right workflow and execute it for this task:\n\n\u003ctask description\u003e\n```\n\n## Why Use Workflows Instead of a Single Prompt?\n\nThe difference is usually not raw model capability. It is process discipline: workflows force triage, validation, and handoff steps that ad hoc prompting often skips.\n\nWorkflows also help absorb silent base-model quality drift. If the underlying model becomes less careful, less reliable, or less consistent without an obvious product change, the workflow still adds checkpoints that reduce the chance of a major hidden drop in output quality.\n\nThe chart below comes from a 6-task exploratory Claude Code study. The full statistical protocol (blinded scoring, bootstrap confidence intervals, paired permutation tests with Holm–Bonferroni correction, inter-rater agreement) is defined in [evaluation/README.md](evaluation/README.md).\n\n![Measured Outcome Comparison](assets/estimated-outcome-comparison.svg)\n\nScoring note: higher is better for every score.\n\nMetric key:\n\n- `TPR`: task pass rate — average task-level pass rate across repeated runs.\n- `RP@k`: reliable pass at k — share of tasks where every repeated run passes.\n- `CPR`: clean pass rate — share of runs that pass, validate, introduce no regression, and need no rework.\n- `RFR`: regression-free rate — share of runs with no unrelated regression and, when declared, passing locked evaluator checks.\n- `NRR`: no-rework rate — share of runs that need no repair pass.\n\nInterpretation:\n\n- `Task Pass Rate` improves because workflows help execution discipline and validation, not because they change the underlying model's raw capability.\n- `Reliable Pass@k` improves more noticeably because workflows reduce variance by making the agent follow a stable sequence of triage, implementation, and validation steps.\n- `Clean Pass Rate` is the strictest headline quality metric because a run must pass acceptance criteria, pass validation, avoid unrelated regressions, and need no repair pass.\n- `Regression-Free Rate` and `No-Rework Rate` improve because workflows reduce mistakes by enforcing baseline capture, hidden regression/evaluator checks, and post-change revalidation.\n- Workflows are also more resilient to silent base-model regressions, because process checkpoints catch quality drops that a one-shot prompt may otherwise let through unchecked.\n\n## Available Workflows\n\n- [project-initialization-agent-workflow.md](project-initialization-agent-workflow.md): Bootstrap a new project from requirements through scaffolding, validation, and handoff.\n- [feature-development-agent-workflow.md](feature-development-agent-workflow.md): Design, implement, review, and hand off medium-to-large feature work.\n- [bug-fix-agent-workflow.md](bug-fix-agent-workflow.md): Reproduce, diagnose, fix, and validate a bug.\n- [code-review-agent-workflow.md](code-review-agent-workflow.md): Review code changes with structured findings and optional post-fix re-review.\n- [incident-debugging-agent-workflow.md](incident-debugging-agent-workflow.md): Mitigate production impact first, then diagnose root cause and track follow-up work.\n- [refactoring-agent-workflow.md](refactoring-agent-workflow.md): Improve structure without changing behavior, with baseline and revalidation steps.\n- [tech-debt-cleanup-agent-workflow.md](tech-debt-cleanup-agent-workflow.md): Survey, scope, and execute cleanup work incrementally.\n\n## Shared Building Blocks\n\n- [shared/repository-preflight.md](shared/repository-preflight.md): Repository-aware preflight prompts for coding, review, and incident workflows.\n- [shared/safety-rules.md](shared/safety-rules.md): Reusable safety-rule blocks for different workflow types.\n- [shared/workflow-conventions.md](shared/workflow-conventions.md): Shared conventions for scope control, escalation, baselines, validation, and reporting.\n\n## Bundled Skills\n\nThis repository includes Codex skills for using and maintaining the workflow library:\n\n- [skills/workflow-automation/](skills/workflow-automation/): Routes tasks to the correct workflow and loads the minimum required files.\n- [skills/project-initialization/](skills/project-initialization/): Bootstraps new projects and greenfield repositories using the project initialization workflow.\n- [skills/workflow-maintainer/](skills/workflow-maintainer/): Audits workflow docs, shared references, skill metadata, links, and README inventory for drift.\n- [skills/release-prep/](skills/release-prep/): Prepares release readiness reports, validation evidence, and release-note drafts.\n- [skills/security-review/](skills/security-review/): Performs focused security reviews for auth, permissions, secrets, injection, data exposure, and dependency risk.\n- [skills/test-strategy/](skills/test-strategy/): Designs behavior-to-coverage matrices, regression plans, QA steps, and validation command sets.\n- [skills/migration-planning/](skills/migration-planning/): Plans safe schema, data, API, contract, and rollout migrations.\n- [skills/performance-review/](skills/performance-review/): Reviews changes for scalability, query, caching, memory, latency, and load risks.\n- [skills/docs-maintenance/](skills/docs-maintenance/): Maintains documentation structure, examples, links, headings, and cross-file consistency.\n\nShared support files for bundled skills live in [skills/_shared/](skills/_shared/). This is not an installable skill; it contains reusable helper scripts and shared operating rules used by the skill folders.\n\nEach installable skill includes one canonical agent metadata file:\n\n- `agents/interface.yaml`\n\nTypical setup:\n\n1. Copy the needed folder from `skills/` into your Codex skills directory.\n2. Make sure the skill can find this repository, either by running it from a workspace that contains `agent-workflows/` or by setting `AGENT_WORKFLOWS_ROOT`.\n3. Invoke it with a task such as:\n\n```text\nUse $workflow-automation to route and execute the right workflow for this task:\n\n\u003ctask description\u003e\n```\n\n## Repository Structure\n\n```text\nagent-workflows/\n|- README.md\n|- how-to-use-agent-workflows.md\n|- project-initialization-agent-workflow.md\n|- feature-development-agent-workflow.md\n|- bug-fix-agent-workflow.md\n|- code-review-agent-workflow.md\n|- incident-debugging-agent-workflow.md\n|- refactoring-agent-workflow.md\n|- tech-debt-cleanup-agent-workflow.md\n|- shared/\n|  |- repository-preflight.md\n|  |- safety-rules.md\n|  |- workflow-conventions.md\n|- skills/\n   |- _shared/\n   |- workflow-automation/\n   |- project-initialization/\n   |- workflow-maintainer/\n   |- release-prep/\n   |- security-review/\n   |- test-strategy/\n   |- migration-planning/\n   |- performance-review/\n   |- docs-maintenance/\n```\n\n## When Not to Use This Library\n\n- **One-line fixes** with no ambiguity (typo, constant, import) — just make the change.\n- **Greenfield project setup without meaningful decisions** — if the project is a single script or throwaway prototype, scaffold it directly. For projects with real tech-stack, structure, or tooling decisions, use the [project initialization workflow](project-initialization-agent-workflow.md).\n- **Infrastructure-as-code or CI/CD implementation changes** — the feature, bug-fix, refactoring, and cleanup workflows are oriented around application code. Code review and incident workflows can still be used to inspect infrastructure-related changes.\n- **Pure documentation changes** (README updates, runbook creation) — the overhead of a full workflow is not justified.\n- **Exploratory prototyping** — if the goal is to experiment and throw away code, skip the process.\n\nIf you are unsure, the triage gates inside each workflow will tell you to use a lighter process when the task is small enough.\n\n## Contributing\n\nIssues and pull requests are welcome.\n\nWhen contributing:\n\n- Keep workflow-specific guidance in the relevant workflow file.\n- Move repeated boilerplate into `shared/` instead of copying it across multiple files.\n- Keep the automation skill aligned with the workflow library when workflow names, paths, or shared conventions change.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffranklioxygen%2Fagent-workflows","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffranklioxygen%2Fagent-workflows","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffranklioxygen%2Fagent-workflows/lists"}