Skip to content

About

Documentation-first AI workflow generator. Detects your project, generates tailored flows (design, implement, free, parallel-implement, PR, test, deploy, docs, KB sync) with visual diagrams and a self-syncing knowledge base. Works with Claude Code, OpenCode, Cursor, Copilot, Kimi. Markdown-only, zero install.

Topics

Resources

Stars

9 stars

Watchers

0 watching

Forks

Latest commit

 

History

35 Commits

Folders and files

Repository files navigation

ai-flow-anything

Universal workflow generator for AI-assisted development.
Markdown-native. Zero installation. Works with any project type.


What is ai-flow-anything?

ai-flow-anything generates tailored AI-assisted development workflows for your project. It interviews your codebase, asks you about your goals, and produces a complete set of flows that guide AI assistants through your development process.

No code. No DSL. No CLI. Just markdown files that Claude, Cursor, or any AI assistant reads and follows.


Philosophy

  • AI is the engine. All instructions are prose in markdown. The AI reads, interprets, and acts.
  • Documentation-first. Every task starts with design docs and diagrams before code.
  • Living knowledge base. Documentation evolves with the project, capturing patterns and decisions.
  • Universal by default. Works for games, web apps, APIs, mobile apps — anything.
  • Customizable by editing markdown. Add phases, rules, or entirely new flow types by editing files.

Quick Start

1. Clone into your project

cd your-project
git clone https://github.com/yusufkaraaslan/ai-flow-anything.git .ai-workflow

2. Activate the wrapper for your AI platform

Pick the platform you use and follow the install instructions in its directory:

Platform Install guide
Claude Code platforms/claude/README.md
Cursor platforms/cursor/README.md
GitHub Copilot platforms/github-copilot/README.md
OpenCode platforms/opencode/README.md
Kimi Code CLI platforms/kimi-code/README.md

Each wrapper is a thin file that points the AI at the platform-neutral instructions.md. All workflow logic is the same; only the activation mechanism differs per tool.

3. Initialize ai-flow-anything

Ask your AI to initialize ai-flow-anything for the project. Each platform's install guide shows the exact invocation — slash command on platforms that support them (like Claude Code), or natural language anywhere ("initialize ai-flow-anything for this project"). The AI will:

  1. Detect your project type (Unity, Godot, React, FastAPI, etc.)
  2. Ask you about project-specific decisions
  3. Generate flows tailored to your project
  4. Install them to .ai-workflow/flows/

4. Use your flows

Ask the AI to run a flow against a task. Examples (use whatever invocation style your platform supports — slash command on Claude Code, natural language anywhere):

  • "Design a task called my-task" — runs the design flow
  • "Implement the next task flow for my-task" — runs the implement flow
  • "Validate my-task for PR" — runs the PR flow
  • "Sync the knowledge base" — runs the KB sync flow (reconciles docs with reality)

What You Get

After initializing ai-flow-anything, your project has:

.ai-workflow/                       ← ai-flow-anything core + your rendered flows
├── instructions.md                 # Orchestration contract
├── VERSION                         # Installed version (used by the update intent)
├── universal/                      # Non-negotiable rules, workflow structure, KB spec
├── profiles/                       # Generic + your detected profile
├── rules.md                        # Project-specific rule overrides
└── flows/
    ├── design-flow.md              # Design tasks with diagrams
    ├── implement-flow.md           # Implement task flows with validation
    ├── free-flow.md                # Quick fixes, tweaks, small refactors
    ├── parallel-implement-flow.md  # Parallel implementation of all task flows
    ├── pr-flow.md                  # PR lifecycle management
    ├── test-flow.md                # Test planning & execution
    ├── deploy-flow.md              # Deployment & release
    ├── docs-flow.md                # Documentation maintenance
    └── kb-sync-flow.md             # Reconcile KB + task records with the codebase

flow-storage/                       ← the three-tier knowledge base
├── project/                        # Architecture, conventions, patterns, decisions
├── team/                           # Onboarding, workflows, glossary
└── tasks/                          # Per-task records (created by design-flow)

Each task gets its own record under flow-storage/tasks/ that grows as the task moves through the flows:

flow-storage/tasks/my-task/
├── design/                                       # design-flow output
│   ├── task-design.md                            # Design document (immutable after sign-off)
│   ├── task-technical-design.md                  # Technical design (evolves)
│   ├── task-edge-cases.md                        # Edge cases & decisions
│   └── diagrams/
│       ├── class-diagram.puml
│       ├── package-diagram.puml
│       └── sequence-diagram.puml
├── implement/                                    # implement-flow output
│   └── flow-plan/
│       ├── task-flow-01-user-session-store.md    # AI proposes descriptive names
│       ├── task-flow-02-auth-service.md          # Variable number (2-10+) based on complexity
│       ├── task-flow-03-login-form-component.md
│       └── task-flow-04-tests.md                 # Developer approves/modifies
├── test/                                         # test-flow output
├── pr/                                           # pr-flow output
│   └── feedback/                                 # PR feedback records
├── deploy/                                       # deploy-flow output
└── docs/                                         # docs-flow output
    └── lessons-learned.md                        # Post-merge summary

Keeping the Knowledge Base Honest

The knowledge base is trusted context — every flow loads it before doing anything. But projects drift: a test framework gets swapped, a "hard" constraint gets relaxed, tasks ship outside the flows. A stale KB is worse than an empty one, because wrong facts poison every future flow run.

ai-flow-anything defends against this on three levels:

  1. Load-time spot-check (Rule 18) — every flow verifies a few load-bearing KB claims (test framework, numeric constraints, phase labels) against the codebase before trusting them. Contradictions are flagged at the next review gate.
  2. Status drift audit — "Show workflow status" runs read-only doctor checks: task records stuck on pending for shipped features, malformed sign-off blocks, misplaced artifacts, KB files that were never synced.
  3. KB sync flow — "Sync the knowledge base" walks every KB entry and task record, checks each claim against the live codebase, and presents claim → observed reality → proposed fix at review gates. Corrections are applied in place and each verified file gets a Last Synced stamp.

Updating

Installs carry a VERSION file. When a new ai-flow-anything version ships, ask your AI to "update ai-flow-anything" — it re-syncs the core (instructions, universal rules, profiles, wrappers) while preserving your rendered flows, project rules, and knowledge base, and offers per-flow re-render diffs when skeletons changed. One review gate before anything is overwritten.


Project Types Supported

Profile Description Detection
generic Minimal fallback — works for anything Any project
unity-game Unity/C# games Assets/, *.cs, ProjectSettings/
godot-game Godot/GDScript games project.godot, *.gd
web-frontend React/Vue/Angular/Svelte package.json, src/
backend-api FastAPI/Django/Express/Go pyproject.toml, go.mod, Cargo.toml
mobile-app Flutter/React Native pubspec.yaml, ios//android/

How It Works

Developer asks to initialize ai-flow-anything.

AI reads:
  instructions.md                → "I am a workflow generator"
  universal/rules.md              → "These rules apply to all projects"
  profiles/*/README.md            → "Which profile matches this project?"
  
AI detects project type:
  → Scans files, matches against profile detection hints
  → If ambiguous: asks developer
  → If no match: offers to create custom profile

AI loads profile:
  profiles/{detected}/README.md   → "This is a Unity game"
  profiles/{detected}/discovery.md → "Explore the codebase like this..."
  profiles/{detected}/rules.md    → "Follow these Unity-specific rules"
  profiles/{detected}/skeletons/  → "Fill these templates with discovered details"

AI executes discovery:
  → Follows discovery.md instructions
  → Reads files, searches patterns, asks questions
  → Fills slot catalog with project specifics

AI generates flows:
  → Loads skeletons
  → Fills project-specific slots (class names, namespaces, patterns)
  → Applies universal + profile rules
  → Writes to .ai-workflow/flows/

AI presents for review:
  → Shows generated files
  → Developer: [A]ccept / [F]eedback / [R]eject
  → Iterates until accepted

Developer uses flows by asking:
  → "Design a task called my-task"
  → "Implement the next task flow for my-task"
  → "Validate my-task for PR"

Customization

Add a custom rule

Edit .ai-workflow/rules.md in your project:

## Custom Rule: No console.log in production

Severity: error
Check: No `console.log` statements in `src/` unless inside `if (DEBUG)`.

Add a custom flow

Create .ai-workflow/flows/my-flow.md:

# Flow: Security Audit

## Purpose
Run security checks on new tasks.

## Phases
1. Scan for SQL injection risks
2. Check auth middleware coverage
3. Validate input sanitization
4. Report findings

Create a new profile

See docs/how-to-create-profile.md.


Documentation


Contributing

Profiles are community-contributed. To add a new profile:

  1. Copy profiles/generic/ as a starting point
  2. Edit README.md, discovery.md, rules.md
  3. Customize skeletons for your tech stack
  4. Submit a pull request

License

MIT

About

Documentation-first AI workflow generator. Detects your project, generates tailored flows (design, implement, free, parallel-implement, PR, test, deploy, docs, KB sync) with visual diagrams and a self-syncing knowledge base. Works with Claude Code, OpenCode, Cursor, Copilot, Kimi. Markdown-only, zero install.

Topics

Resources

Stars

9 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors