# Agent Workflow Version: 1.0.0 ## Purpose This file defines the day-to-day execution paths used by agents in this repository. `AGENTS.md` defines the rules. `AI-OS.md` defines the operating-system architecture. This file defines **how work flows** from request to completion. --- # 1. Default Workflow Use this lifecycle for substantial work: ```text USER REQUEST ↓ DISCOVER ↓ UNDERSTAND ↓ INITIAL APPROACH ↓ MIRROR AUDIT ↓ PLAN ↓ IMPLEMENT ↓ VERIFY ↓ RED-TEAM ↓ REFINE ↓ DOCUMENT ↓ RETROSPECTIVE ↓ REUSABLE LEARNING? / \ YES NO ↓ ↓ IMPROVE DONE AI-OS ↓ TEST ↓ LOG ↓ DONE ``` Not every task requires every stage. Choose the workflow path based on complexity and risk. --- # 2. Fast Path Use the Fast Path for: * typo fixes * formatting fixes * obvious one-line configuration changes * simple renames * low-risk documentation edits * trivial code corrections * factual repository lookups Flow: ```text DISCOVER ↓ CHANGE ↓ VERIFY ↓ DONE ``` Even trivial work should still be verified when verification is practical. --- # 3. Standard Path Use the Standard Path for: * normal feature work * bug fixes * moderate refactors * scripts * configuration changes * new functions * ordinary integrations * project documentation changes Flow: ```text DISCOVER ↓ UNDERSTAND ↓ INITIAL APPROACH ↓ MIRROR AUDIT ↓ IMPLEMENT ↓ VERIFY ↓ RETROSPECTIVE ↓ DONE ``` A formal written plan is optional if the implementation path is obvious after the audit. --- # 4. High-Risk Path Use the High-Risk Path for: * authentication * authorization * security-sensitive code * production infrastructure * destructive operations * database migrations * data transformations * deployment systems * public APIs * payment logic * compliance-sensitive work * major architecture changes * large refactors * irreversible changes Flow: ```text DISCOVER ↓ DIAGNOSTIC INTAKE ↓ INITIAL APPROACH ↓ MIRROR AUDIT ↓ PLAN ↓ IMPLEMENT INCREMENTALLY ↓ VERIFY EACH PHASE ↓ FULL VERIFICATION ↓ RED-TEAM ↓ REFINE ↓ DOCUMENT ↓ RETROSPECTIVE ↓ REUSABLE LEARNING ``` For destructive or irreversible work, explicitly identify: ```text BACKUP ROLLBACK RECOVERY FAILURE BOUNDARIES ``` before execution. --- # 5. Discovery Phase The purpose of discovery is to replace assumptions with project evidence. Inspect: * relevant instructions * target files * related code * dependencies * configuration * tests * build scripts * deployment scripts * documentation * existing analogous implementations Output of discovery should answer: ```text What exists? What is relevant? What conventions are already used? What constraints are visible? What remains unknown? ``` --- # 6. Understanding Phase Convert discovered information into an operational problem statement. Identify: ```text OBJECTIVE CURRENT STATE DESIRED STATE CONSTRAINTS INVARIANTS DEPENDENCIES SUCCESS CRITERIA ``` Invariants are things that must remain unchanged. Examples: ```text existing URL paths database compatibility public API behavior authentication model file format deployment process ``` --- # 7. Diagnostic Intake Path If critical information cannot be discovered, use: ```text .ai/skills/diagnostic-intake/SKILL.md ``` Flow: ```text UNKNOWN ↓ CAN REPOSITORY ANSWER IT? / \ YES NO ↓ ↓ SEARCH IS IT CRITICAL? / \ YES NO ↓ ↓ ASK USER ASSUME/DEFER ``` Do not ask the user to provide information that is already discoverable. --- # 8. Initial Approach Phase Create a working hypothesis. The initial approach should normally contain: ```text PROPOSED CHANGE WHY THIS FITS THE CURRENT PROJECT FILES OR COMPONENTS INVOLVED DEPENDENCIES ASSUMPTIONS RISKS VERIFICATION STRATEGY ``` Do not overdesign. The purpose is to create something concrete enough to audit. --- # 9. Mirror Audit Phase Use: ```text .ai/skills/mirror-audit/SKILL.md ``` Audit: ```text ASSUMPTIONS EDGE CASES FAILURE MODES DEPENDENCY RISKS SECURITY DATA INTEGRITY PERFORMANCE MAINTAINABILITY ROLLBACK OPERATIONAL COST UNNECESSARY COMPLEXITY ``` The audit should result in one of three states: ```text APPROACH ACCEPTED APPROACH ACCEPTED WITH MITIGATIONS APPROACH REVISED ``` --- # 10. Planning Phase Create a plan only as detailed as necessary. A plan may look like: ```text 1. modify configuration 2. add service 3. update controller 4. add tests 5. run build 6. run targeted smoke test ``` For high-risk work, include: ```text rollback backup migration order deployment order verification gates ``` --- # 11. Incremental Implementation Prefer: ```text SMALL CHANGE ↓ CHECK ↓ NEXT CHANGE ``` over: ```text MANY CHANGES ↓ LARGE TEST FAILURE ↓ UNCLEAR ROOT CAUSE ``` Each coherent phase should leave the repository in an understandable state. --- # 12. Verification Phase Use the strongest available verification. Order of preference: ```text EXISTING TESTS TARGETED TESTS BUILD TYPE CHECK STATIC ANALYSIS LINT SMOKE TEST MANUAL EXECUTION DIRECT INSPECTION ``` Verification should answer: ```text Does it work? Did we preserve required behavior? Did we introduce regressions? Are failure paths handled? ``` --- # 13. Verification Failure Loop If verification fails: ```text FAILURE ↓ REPRODUCE ↓ COLLECT EXACT EVIDENCE ↓ FORM HYPOTHESIS ↓ TEST HYPOTHESIS ↓ FIX ROOT CAUSE ↓ RERUN FAILED CHECK ↓ RERUN BROADER CHECKS ``` Do not respond to failure with random changes. --- # 14. Debug Loop For debugging tasks: ```text SYMPTOM ↓ REPRODUCE ↓ BOUND THE FAILURE ↓ TRACE DATA / CONTROL FLOW ↓ FORM HYPOTHESES ↓ RANK HYPOTHESES ↓ TEST CHEAPEST DISCRIMINATING HYPOTHESIS ↓ IDENTIFY ROOT CAUSE ↓ FIX ↓ VERIFY ``` A good debugging step should reduce uncertainty. --- # 15. Hypothesis Ranking When several causes are possible, prioritize by: ```text likelihood cost to test ability to discriminate risk of destructive testing ``` Prefer a cheap test that clearly rules out several possibilities. --- # 16. Red-Team Phase After consequential work passes normal verification, use: ```text .ai/skills/red-team/SKILL.md ``` Select a perspective based on risk. Examples: ```text SECURITY → attacker / security reviewer DATABASE → DBA DEPLOYMENT → infrastructure engineer MAINTAINABILITY → future developer PERFORMANCE → performance engineer BUSINESS PROCESS → end user / operator ``` The red-team review should not replace normal testing. It adds a second form of scrutiny. --- # 17. Refinement Phase Use red-team findings and verification evidence to decide: ```text MUST FIX SHOULD FIX ACCEPTABLE TRADEOFF SPECULATIVE CONCERN ``` Do not fix every hypothetical issue. Prioritize real risk. --- # 18. Documentation Phase Update documentation when future users, developers, operators, or agents need to know about the change. Potential updates include: ```text README architecture docs deployment docs runbooks configuration docs API docs troubleshooting docs agent skills ``` Do not document temporary debugging details unless they reveal a reusable operational lesson. --- # 19. Learning Workflow When the user wants to learn something rather than merely get the answer: ```text ESTABLISH BASELINE ↓ ONE MICRO-CONCEPT ↓ ONE DRILL ↓ WAIT FOR USER ↓ EVALUATE ↓ NEXT MICRO-CONCEPT ``` Use: ```text .ai/skills/socratic-teacher/SKILL.md ``` --- # 20. Learning Error Handling If the learner is correct: ```text CONFIRM WHY ↓ ADVANCE ``` If partially correct: ```text IDENTIFY MISSING VARIABLE ↓ ASK FOR REVISION ``` If incorrect: ```text IDENTIFY LOGIC BREAK ↓ SIMPLER ANALOGY ↓ SIMPLER RETRY ``` Avoid fake praise. --- # 21. Prompt Creation Workflow When a repeatable task needs a production prompt: ```text DEFINE GOAL ↓ IDENTIFY INPUTS ↓ IDENTIFY OUTPUT ↓ IDENTIFY CONSTRAINTS ↓ IDENTIFY FAILURE MODES ↓ BUILD PROMPT ↓ TEST NORMAL INPUT ↓ TEST INCOMPLETE INPUT ↓ TEST EDGE CASE ↓ REFINE ↓ SAVE IF REUSABLE ``` Use: ```text .ai/skills/prompt-architect/SKILL.md ``` --- # 22. Prompt Failure Workflow When a prompt produces poor output: ```text FAILED PROMPT + OUTPUT ↓ DIAGNOSE FAILURE CLASS ↓ MAKE SMALLEST REPAIR ↓ RERUN SAME TEST ↓ COMPARE ↓ PROMOTE FIX IF REUSABLE ``` Use: ```text .ai/skills/prompt-debugger/SKILL.md ``` Possible failure classes: ```text MISSING CONTEXT WEAK CONSTRAINTS CONFLICTING INSTRUCTIONS INSTRUCTION OVERLOAD WRONG TOOL ASSUMPTIONS POOR OUTPUT CONTRACT STALE FACTS WRONG INTERACTION MODE WRONG PERSONA ``` --- # 23. Reverse Engineering Workflow When a gold-standard artifact exists: ```text GOLD STANDARD ↓ EXTRACT ROLE / CONTEXT ↓ EXTRACT STRUCTURE ↓ EXTRACT BOUNDARIES ↓ GENERALIZE VARIABLES ↓ CREATE SCAFFOLD ↓ TEST ON DIFFERENT SCENARIO ``` Use: ```text .ai/skills/reverse-engineer/SKILL.md ``` --- # 24. Retrospective Workflow After substantial work: ```text TASK COMPLETE ↓ WHAT WORKED? ↓ WHAT FAILED? ↓ WHAT ASSUMPTION WAS WRONG? ↓ WHAT CHECK FOUND IT? ↓ WHAT SHOULD HAVE FOUND IT EARLIER? ↓ IS THE LESSON REUSABLE? ``` Use: ```text .ai/skills/retrospective/SKILL.md ``` --- # 25. Self-Improvement Workflow If a reusable lesson exists: ```text OBSERVATION ↓ CAPTURE IN LEARNINGS.md ↓ CLASSIFY ↓ SEARCH EXISTING GUIDANCE ↓ CHOOSE DESTINATION ↓ SMALLEST USEFUL CHANGE ↓ SYSTEM AUDIT ↓ TEST ↓ CHANGELOG ↓ REUSE ``` --- # 26. Skill Extraction Workflow When a task reveals a reusable procedure: ```text REAL TASK ↓ REUSABLE PATTERN? / \ NO YES ↓ ↓ DONE EXTRACT ↓ GENERALIZE ↓ EXISTING SKILL? / \ YES NO ↓ ↓ EXTEND CREATE \ / ↓ ↓ TEST ↓ VERSION ↓ CHANGELOG ``` Use: ```text .ai/skills/skill-extractor/SKILL.md ``` --- # 27. New Skill Workflow When creating a new skill: ```text DEFINE PURPOSE ↓ DEFINE TRIGGER ↓ DEFINE INPUTS ↓ DEFINE PROCEDURE ↓ DEFINE OUTPUT ↓ DEFINE VERIFICATION ↓ DEFINE FAILURE HANDLING ↓ TEST ORIGINAL SCENARIO ↓ TEST SECOND SCENARIO ↓ ACTIVATE ``` Use: ```text .ai/skills/skill-builder/SKILL.md ``` --- # 28. AI-System Change Workflow Changes to: ```text AGENTS.md CLAUDE.md AI-OS.md WORKFLOW.md active skills ``` must follow: ```text EVIDENCE ↓ SCOPE DECISION ↓ SMALL EDIT ↓ SYSTEM AUDIT ↓ BEHAVIOR TEST ↓ REGRESSION TEST ↓ CHANGELOG ``` --- # 29. System Audit Workflow Use: ```text .ai/skills/system-audit/SKILL.md ``` Check: ```text AUTHORITY CONFLICTS DUPLICATION SCOPE EXPECTED BEHAVIOR REGRESSIONS BLOAT BROKEN REFERENCES ROLLBACK ``` A self-improvement is not complete until it passes this audit. --- # 30. Project Bootstrap Workflow When the AI-OS is first introduced into an unfamiliar repository: ```text READ ROOT INSTRUCTIONS ↓ IDENTIFY LANGUAGES ↓ IDENTIFY FRAMEWORKS ↓ IDENTIFY BUILD ↓ IDENTIFY TESTS ↓ IDENTIFY DATABASE ↓ IDENTIFY DEPLOYMENT ↓ IDENTIFY ARCHITECTURE ↓ IDENTIFY SECURITY BOUNDARIES ↓ IDENTIFY CONVENTIONS ↓ CAPTURE PROJECT CONTEXT ``` Project facts should normally be stored in project documentation or a dedicated project-context file. Do not put all discovered project facts into `AGENTS.md`. --- # 31. Repeated Task Detection When performing work, watch for repeated operations. Examples: ```text same file setup same controller structure same deployment sequence same validation same database procedure same troubleshooting steps ``` Repeated work is a signal that: ```text AUTOMATION SKILL TEMPLATE PROMPT TEST ``` may be justified. --- # 32. Automation Candidate Workflow When repeated manual work is discovered: ```text REPEATED STEP ↓ IS IT DETERMINISTIC? / \ NO YES ↓ ↓ SKILL SCRIPT/AUTOMATION CANDIDATE ``` Before automating, consider: ```text failure handling idempotency rollback logging environment assumptions security ``` --- # 33. Escalation Workflow Surface an issue to the user when: ```text the requirement is truly ambiguous a destructive operation is unavoidable the requested approach creates serious risk required credentials or permissions are missing two user goals conflict a major AI-OS change is needed the task cannot be verified safely ``` Do not escalate merely because implementation requires effort. --- # 34. Assumption Workflow When an assumption is necessary: ```text CAN IT BE DISCOVERED? ↓ YES → DISCOVER IT NO ↓ IS WRONG ASSUMPTION HIGH-RISK? ↓ YES → ASK / SURFACE NO ↓ STATE ASSUMPTION ↓ PROCEED ``` --- # 35. Failure Recording Not every failure belongs in permanent project history. Record a failure in the learning ledger when it reveals: ```text reusable diagnostic insight repeated process weakness missing validation bad instruction recurring environmental assumption ``` Do not record ordinary typos or one-off mistakes unless they represent a pattern. --- # 36. Completion Workflow Before declaring substantial work complete: ```text REQUEST SATISFIED? ↓ VERIFIED? ↓ REGRESSION CHECKED? ↓ RISKS CONSIDERED? ↓ DOCS UPDATED? ↓ REUSABLE LEARNING CONSIDERED? ↓ AI-SYSTEM CHANGES TESTED + LOGGED? ↓ DONE ``` --- # 37. Preferred Agent Mindset Do not treat work as: ```text REQUEST ↓ GENERATE ↓ DONE ``` Treat it as: ```text REQUEST ↓ UNDERSTAND ↓ BUILD ↓ PROVE ↓ LEARN ``` The quality of the workflow matters because it compounds across future tasks.