AI_AGENT_OS/.ai/WORKFLOW.md

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:

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:

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:

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:

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:

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:

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:

OBJECTIVE

CURRENT STATE

DESIRED STATE

CONSTRAINTS

INVARIANTS

DEPENDENCIES

SUCCESS CRITERIA

Invariants are things that must remain unchanged.

Examples:

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:

.ai/skills/diagnostic-intake/SKILL.md

Flow:

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:

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:

.ai/skills/mirror-audit/SKILL.md

Audit:

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:

APPROACH ACCEPTED

APPROACH ACCEPTED WITH MITIGATIONS

APPROACH REVISED

---

10. Planning Phase

Create a plan only as detailed as necessary.

A plan may look like:

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:

rollback

backup

migration order

deployment order

verification gates

---

11. Incremental Implementation

Prefer:

SMALL CHANGE
   ↓
CHECK
   ↓
NEXT CHANGE

over:

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:

EXISTING TESTS

TARGETED TESTS

BUILD

TYPE CHECK

STATIC ANALYSIS

LINT

SMOKE TEST

MANUAL EXECUTION

DIRECT INSPECTION

Verification should answer:

Does it work?

Did we preserve required behavior?

Did we introduce regressions?

Are failure paths handled?

---

13. Verification Failure Loop

If verification fails:

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:

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:

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:

.ai/skills/red-team/SKILL.md

Select a perspective based on risk.

Examples:

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:

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:

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:

ESTABLISH BASELINE
   ↓
ONE MICRO-CONCEPT
   ↓
ONE DRILL
   ↓
WAIT FOR USER
   ↓
EVALUATE
   ↓
NEXT MICRO-CONCEPT

Use:

.ai/skills/socratic-teacher/SKILL.md

---

20. Learning Error Handling

If the learner is correct:

CONFIRM WHY
   ↓
ADVANCE

If partially correct:

IDENTIFY MISSING VARIABLE
   ↓
ASK FOR REVISION

If incorrect:

IDENTIFY LOGIC BREAK
   ↓
SIMPLER ANALOGY
   ↓
SIMPLER RETRY

Avoid fake praise.

---

21. Prompt Creation Workflow

When a repeatable task needs a production prompt:

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:

.ai/skills/prompt-architect/SKILL.md

---

22. Prompt Failure Workflow

When a prompt produces poor output:

FAILED PROMPT + OUTPUT
   ↓
DIAGNOSE FAILURE CLASS
   ↓
MAKE SMALLEST REPAIR
   ↓
RERUN SAME TEST
   ↓
COMPARE
   ↓
PROMOTE FIX IF REUSABLE

Use:

.ai/skills/prompt-debugger/SKILL.md

Possible failure classes:

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:

GOLD STANDARD
   ↓
EXTRACT ROLE / CONTEXT
   ↓
EXTRACT STRUCTURE
   ↓
EXTRACT BOUNDARIES
   ↓
GENERALIZE VARIABLES
   ↓
CREATE SCAFFOLD
   ↓
TEST ON DIFFERENT SCENARIO

Use:

.ai/skills/reverse-engineer/SKILL.md

---

24. Retrospective Workflow

After substantial work:

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:

.ai/skills/retrospective/SKILL.md

---

25. Self-Improvement Workflow

If a reusable lesson exists:

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:

REAL TASK
   ↓
REUSABLE PATTERN?
   /       \
 NO         YES
 ↓           ↓
DONE      EXTRACT
             ↓
        GENERALIZE
             ↓
      EXISTING SKILL?
        /        \
      YES         NO
       ↓           ↓
    EXTEND       CREATE
       \           /
        ↓         ↓
           TEST
            ↓
          VERSION
            ↓
         CHANGELOG

Use:

.ai/skills/skill-extractor/SKILL.md

---

27. New Skill Workflow

When creating a new skill:

DEFINE PURPOSE
   ↓
DEFINE TRIGGER
   ↓
DEFINE INPUTS
   ↓
DEFINE PROCEDURE
   ↓
DEFINE OUTPUT
   ↓
DEFINE VERIFICATION
   ↓
DEFINE FAILURE HANDLING
   ↓
TEST ORIGINAL SCENARIO
   ↓
TEST SECOND SCENARIO
   ↓
ACTIVATE

Use:

.ai/skills/skill-builder/SKILL.md

---

28. AI-System Change Workflow

Changes to:

AGENTS.md

CLAUDE.md

AI-OS.md

WORKFLOW.md

active skills

must follow:

EVIDENCE
   ↓
SCOPE DECISION
   ↓
SMALL EDIT
   ↓
SYSTEM AUDIT
   ↓
BEHAVIOR TEST
   ↓
REGRESSION TEST
   ↓
CHANGELOG

---

29. System Audit Workflow

Use:

.ai/skills/system-audit/SKILL.md

Check:

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:

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:

same file setup

same controller structure

same deployment sequence

same validation

same database procedure

same troubleshooting steps

Repeated work is a signal that:

AUTOMATION

SKILL

TEMPLATE

PROMPT

TEST

may be justified.

---

32. Automation Candidate Workflow

When repeated manual work is discovered:

REPEATED STEP
   ↓
IS IT DETERMINISTIC?
   /       \
 NO         YES
 ↓           ↓
SKILL       SCRIPT/AUTOMATION CANDIDATE

Before automating, consider:

failure handling

idempotency

rollback

logging

environment assumptions

security

---

33. Escalation Workflow

Surface an issue to the user when:

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:

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:

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:

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:

REQUEST
   ↓
GENERATE
   ↓
DONE

Treat it as:

REQUEST
   ↓
UNDERSTAND
   ↓
BUILD
   ↓
PROVE
   ↓
LEARN

The quality of the workflow matters because it compounds across future tasks.