Varietyz/Disciplined-AI-Software-Development — Workflow

Stage overview

The methodology enforces a four-stage sequence that must be followed in order. Stages are not phases in a CI/CD pipeline — they are context-loading and instruction-delivery patterns for AI sessions.

Stage 1: AI Behavioral Configuration
         ↓
Stage 2: Collaborative Planning
         ↓
Stage 3: Systematic Implementation
         ↓
Stage 4: Data-Driven Iteration

Stage 1 — AI Behavioral Configuration

Before any coding conversation begins, the AI tool is primed with two artifacts:

1. AI-PREFERENCES.md / AI-PREFERENCES.XML — pasted as custom instructions (ChatGPT), system prompt (Claude), or equivalent. Establishes behavioral constraints: file size limits, separation of concerns, single-responsibility rule.

2. A persona — one of GUIDE-PERSONA.json, TECDOC-PERSONA.json, R&D-PERSONA.json, MURMATE-PERSONA.json, uploaded to the session. Prevents behavioral drift across long sessions.

The CORE-PERSONA-FRAMEWORK.json base is loaded first; then a plugin persona extends it.

Gate: The AI must acknowledge the constraints before proceeding. Behavioral configuration is a prerequisite, not optional context.

Stage 2 — Collaborative Planning

METHODOLOGY.md / METHODOLOGY.XML is shared with the AI. The AI and developer jointly produce:

• Architectural blueprint (module map, dependency graph)
• Component boundaries (each module must be a single responsibility, ≤ 150 lines)
• Data model (defined before any implementation)
• Testing strategy (test infrastructure before application logic)
• Performance benchmarks (targets set before writing code)

Phase 0 (mandatory pre-implementation)

Before any feature logic, Phase 0 must be completed:

Phase 0 checklist:
  □ Benchmarking infrastructure (performance baselines)
  □ CI/CD pipeline
  □ Core architecture modules
  □ Test suite scaffolding
  □ Data model finalized

The rationale: "Planning thoroughly upfront typically prevents days of fixing architectural issues later."

Stage 3 — Systematic Implementation

The developer implements one component per AI interaction. Each interaction is bounded:

• Single component — one file, one responsibility
• File size ≤ 150 lines (≤ 250 for web components)
• Validation before proceeding — AI confirms constraints satisfied before moving to the next component

PAG constraint enforcement format:

CONSTRAINT file_size_limit:
    SET max_lines = 150
    ALWAYS: Split files exceeding max_lines INTO separate_modules
    NEVER: Create monolithic files

The GUIDE-PERSONA is active during this stage to enforce the 150-line limit and prevent "vibe coding" — writing broad, unfocused implementations.

Stage 4 — Data-Driven Iteration

After implementation, the developer returns to the benchmarking infrastructure created in Phase 0 and measures against the baseline. Iteration is driven by data, not intuition.

The R&D-PERSONA is appropriate for this stage — it brings "absolute code quality standards" and a research-scientist perspective to analyzing benchmark results.

Codebase snapshot workflow

Between sessions, scripts/project_extract.py generates a structured snapshot:

python scripts/project_extract.py
  → THE_PROJECT.md  (single-file output, SEPARATE_FILES=False)
  → OR: separate per-module files (SEPARATE_FILES=True)

This snapshot is shared with the AI at the beginning of the next session to restore context without manually re-reading files.

Dual-format PAG usage

PAG instructions can replace natural-language instructions for precision:

PAG is specifically noted as "particularly effective when you need explicit validation gates and constraint enforcement."

Session discipline

The methodology addresses AI behavioral degradation in long sessions:

• Start of session: load persona (prevents drift from a clean behavioral baseline)
• During session: AI operates under PAG constraints (reduces interpretive ambiguity)
• End of session: snapshot via project_extract.py (preserves context for next session)
• New session: reload persona + snapshot (resets behavioral baseline)

There are no automated hooks or scripts enforcing these — all discipline is manual and convention-based.

Varietyz/Disciplined-AI-Software-Development — Memory & Context

Memory model: file-based snapshot

There is no persistent memory system, database, or automated state management. Memory is entirely manual and file-based.

The only memory mechanism is scripts/project_extract.py — a snapshot generator that produces a structured text file representing the entire codebase at a point in time.

project_extract.py behavior

# Key configuration flags (from source analysis):
SEPARATE_FILES = False   # True → per-module files; False → single THE_PROJECT.md
# Output: THE_PROJECT.md (default) or structured directory of module files

The script walks the project directory, reads each source file, and compiles them into a structured snapshot. The snapshot is then pasted or uploaded to a new AI session.

What the snapshot contains:

• Project directory structure
• Each module's full source (or truncated if size limit configured)
• Metadata (file paths, line counts)

What it does not contain:

• Conversation history
• AI decisions or rationale from previous sessions
• Specification documents (those are managed separately)

Context strategy: persona as behavioral memory

The personas serve as a form of behavioral memory — not project state memory, but AI behavior consistency:

• Without persona reload: AI may "drift" in long sessions — gradually producing inconsistent code style, ignoring constraints, or reverting to default behaviors
• With persona reload at session start: AI behavioral constraints are restored from a clean baseline

This is described in the methodology as a key problem that the persona system solves: "behavioral pattern degradation" across extended AI sessions.

Cross-session handoff protocol

No automated mechanism. The developer manually:

1. Runs project_extract.py before ending a session
2. Saves the generated snapshot
3. At the next session start:
   • Uploads CORE-PERSONA-FRAMEWORK.json + active persona
   • Shares AI-PREFERENCES.md as custom instructions
   • Uploads THE_PROJECT.md snapshot
   • References METHODOLOGY.md for planning context

This is a convention, not an enforced workflow. There are no hooks, no CLAUDE.md session-start commands, no registry tracking.

Context window management philosophy

The methodology's primary context-management technique is file size constraints, not memory tooling:

"Small files and bounded problems prevent the AI from juggling multiple concerns simultaneously."

By enforcing ≤ 150 lines per module:

• Each AI interaction stays bounded to a single file's context
• No module requires the AI to hold multiple large files simultaneously
• The codebase remains "shareable" — THE_PROJECT.md stays small enough to paste

The 150-line limit is described as both an architectural constraint and a context window optimization.

FAQ file (questions_answers/)

The questions_answers/ directory contains FAQ content. This is documentation for the developer, not input to AI sessions — it answers common questions about applying the methodology, but is not loaded into AI context.

No automated context compaction

Unlike spec-driver (which has a PostToolUse hook for artifact tracking), the methodology has no automated context compaction, no drift detection hooks, and no session state files. All context management is manual.

Scope of memory

Varietyz/Disciplined-AI-Software-Development — Orchestration

Orchestration model: none

This is a single-AI, single-session methodology. There is no multi-agent orchestration, no parallel subagent spawning, no pipeline of specialized AI workers.

The "orchestration" in this methodology is human-driven:

• Developer decides which stage to operate in
• Developer selects which persona to load
• Developer decides which component to implement next
• Developer runs the snapshot script between sessions

Persona system as role-based coordination

The closest analog to orchestration is the persona system — swapping which persona is active for different work types:

This is sequential role assignment, not concurrent agent spawning. One persona is active at a time. The developer manually switches by uploading a different persona JSON.

PAG-AGENT-ORCHESTRATION.md

For CLI agents (Claude Code, Cursor, Windsurf), the methodology provides PAG-AGENT-ORCHESTRATION.md — a PAG-syntax version of the methodology adapted for agentic tool use.

Key difference from PAG-COLLABORATION.md: assumes the AI has file read/write access rather than requiring the developer to paste content. The constraints are the same; the delivery mechanism differs.

This document does not define multi-agent pipelines — it defines constraints for a single CLI agent session.

No spawning mechanism

There is no:

• Claude Code claude-task-tool usage
• Subagent definition files
• Parallel execution tracks
• Agent registry or coordination protocol

The methodology is designed to work with any AI tool as a single session, not to build infrastructure requiring specific AI agent capabilities.

Decision processing philosophy

The methodology's position on multi-step AI tasks:

"AI handles 'Can you do A?' more reliably than 'Can you do A, B, C, D, E, F, G, H?' — Decision Processing: AI handles focused objectives."

This is an anti-orchestration philosophy: rather than asking AI to manage complex multi-step work, the developer decomposes all work into single-objective interactions before any AI session begins. The decomposition happens in Stage 2 (Collaborative Planning), not at runtime.

Validation gates

Though not implemented as automated hooks, the methodology defines validation checkpoints in PAG:

CONSTRAINT separation_of_concerns:
    FOR EACH module IN codebase:
        VALIDATE module HAS single_responsibility
        VALIDATE module HAS clear_interfaces
    END FOR

These are instructions to the AI, not automated checks. The AI is expected to self-validate against constraints before producing output.

Execution mode

Interactive loop. Developer interacts with AI on one component per session turn, validates output against PAG constraints, then proceeds to the next component. No batch processing, no background agents.

Cross-tool portability

The methodology's multi-format approach (Markdown + XML + JSON + PAG) is explicitly designed to work across:

• Web browser AI tools (ChatGPT, Claude web, Gemini)
• CLI agents (Claude Code, Cursor, Windsurf)

The same four-stage methodology is portable across all — only the instruction delivery format changes.

Varietyz/Disciplined-AI-Software-Development — UI & CLI Surface

No dedicated CLI or UI

Disciplined-AI-Software-Development has no CLI binary, no web dashboard, no TUI, and no installable tool. It is a methodology document collection.

The only executable component is a Python utility script.

scripts/project_extract.py

Purpose: Generate a structured codebase snapshot for sharing with AI sessions.

Usage:

python scripts/project_extract.py

Configuration (edit variables at top of script):

• SEPARATE_FILES = False — output single THE_PROJECT.md or per-module files
• Other configuration inferred from script source (directory exclusions, file size limits)

Output: THE_PROJECT.md — a structured text file containing the project's full source, formatted for pasting or uploading to AI chat sessions.

This is the only developer-facing tooling in the repository.

Installation surface

The README states "Copy claude-setup/ into your project" but no such directory exists. The actual methodology files live at the repository root.

Claude Code surface

For Claude Code specifically, the methodology provides:

• CLAUDE.md — project-specific guidance at project root
• PAG-AGENT-ORCHESTRATION.md — PAG-syntax constraints for agentic file-reading sessions
• AI-PREFERENCES.XML — machine-parseable custom instructions

No commands, no skills, no hooks. Claude Code integration is documentation-only.

Mermaid diagrams

mermaid_svg/ directory contains architecture diagrams. These are SVG files generated from Mermaid source — visual documentation of the methodology, not interactive tooling.

PAG templates

pag_templates/ directory contains template files for writing PAG instructions. These are scaffolding documents developers fill in when applying the methodology to a new project — not executable code.

Target environment

Comparison note

Unlike spec-driver (which ships a dedicated spec-driver CLI with 8 subcommands and a live TUI), or specorator (which ships a Claude plugin with 18 commands), Disciplined-AI is entirely tooling-free. All interaction is through AI chat sessions directly, with methodology documents as the only interface.