AI Development Flow - spinningideas/resources GitHub Wiki

AI-Enabled Development Flow

This document outlines a "somewhat standard" AI-enabled development flow leveraging "Agentic Harness" frameworks and methodologies.

Inspiration is provided and taken from Superpowers, GSD, SpecKit, and the BMad Method. See also: https://github.com/spinningideas/resources/wiki/AI-Agent-Harnesses + https://github.com/spinningideas/resources/wiki/AI-Assisted-Product-Development

Process Overview

1. Gather Context and Resources

  • Objective: Establish the foundation for the agent.
  • Action: Collect necessary skills, plugins, and agent context resources applicable to the specific project. Ensure the AI has access to relevant documentation, codebase context, and required toolsets. See the Skills section below for how to curate and apply this toolset.

2. Research the Feature/Idea

  • Objective: Understand the requirements and constraints.
  • Action: Investigate the feature or idea. This includes analyzing existing code, understanding dependencies, and researching potential technical approaches or libraries needed for implementation.

3. Plan and Groom (Task Breakdown)

  • Objective: Break the work into small, independently verifiable tasks that an agent can execute in a tight build/test loop.
  • Action: Produce a hierarchical task breakdown before any code is written.
    • Numbering: Use major and minor steps (e.g., 1.0, 1.1, 1.1.1). Major steps represent a capability or milestone; minor steps represent concrete units of work.
    • Task sizing: Each leaf task should be small enough to complete, build, and test in a single Ralph loop iteration (typically under ~30-60 minutes of agent work). Split anything larger.
    • Task contents: For every leaf task capture:
      • Scope: What files/areas are touched and whether it is a modification to existing code or greenfield.
      • Inputs/Dependencies: Preceding tasks, data shapes, models, services, or external APIs required.
      • Acceptance criteria: Observable behavior, required logs, or UI outcomes.
      • Build targets: Which projects/apps must compile cleanly (e.g., backend, frontend, each affected app).
      • Test targets: Specific unit/integration/e2e tests to add or update and the exact commands to run them.
      • Rollback/impact notes: Anything that could break adjacent features.
    • Ordering: Sequence tasks so that each one leaves the repo in a buildable, test-passing state. Prefer depth-first completion of a vertical slice over broad horizontal changes.
    • Parallelization: Mark tasks that are safe to run in parallel via sub-agents and note any shared files that would force serialization.

4. Develop Feature (Ralph Loop per Task)

  • Objective: Execute each task through a disciplined build/test loop so the repo never drifts into a broken state.
  • Action: For every leaf task from step 3, run the Ralph loop until the task's acceptance criteria are met:
    1. Implement: Make the minimal change required for the current task only.
    2. Build: Run all relevant build/compile/type-check commands for the affected projects. If the build fails, fix and repeat step 2 before doing anything else.
    3. Test: Run the task's declared test targets plus any broader regression suite the task can affect. If tests fail, fix and return to step 2.
    4. Lint/format: Run project linters/formatters and resolve issues.
    5. Self-review: Re-read the diff against the task's acceptance criteria; remove dead code, stray logs, and unrelated changes.
    6. Mark done: Only mark the task complete when build, tests, and lint all pass. Commit (or checkpoint) before starting the next task.
    • Loop exit rule: A task is never considered done while any build is broken or any test is failing or skipped without justification. If blocked, split the task, capture the blocker, and re-plan rather than leaving the loop in a failing state.
    • Sub-agents: When delegating a task to a sub-agent, require it to run the same Ralph loop and return only a green build/test result.

5. Test and Verify (Feature-Level)

  • Objective: Confirm the assembled feature works end-to-end and introduces no regressions beyond what the per-task loops covered.
  • Action: After all tasks pass their individual Ralph loops, run the full test suite (unit, integration, and e2e where applicable) and exercise the feature through its primary user flows. Add any missing higher-level tests discovered during integration and re-run the Ralph loop on any task whose scope they touch.

6. Accept Feature

  • Objective: Finalize the development cycle for the feature.
  • Action: Once all tasks are completed and tests are created and successfully run, formally mark the feature as done.

7. Record Learnings and Update

  • Objective: Continuous improvement of the AI harness and process.
  • Action: Document any learnings from the development cycle. Update resources, such as the skills or plugins used, to improve future performance. Fold these learnings back into the agentic harness and the overall development process.

Skills

Skills are the reusable units of context, instructions, and tooling (prompts, plugins, MCP servers, scripts, rules) that an agent loads to perform work competently in a given domain. They are what turn a general-purpose model into a project-aware collaborator.

  • Why skills matter: The quality of agent output is bounded by the quality of the context and toolset it is given. Curated skills encode conventions, guardrails, preferred libraries, test commands, and domain knowledge so the agent does not have to rediscover them each run.
  • Driving the process with skills: At every step of the flow above (gather, research, plan, develop, test, accept, record) the agent should be primed with the skills and plugins relevant to that step - e.g., a planning skill for task breakdown, a build/test skill for the Ralph loop, a code-review skill before marking tasks done.
  • Ever-changing by nature: Skills are not static. Models, tools, MCP servers, frameworks, and project conventions evolve constantly. Expect to add, revise, and retire skills regularly, and treat step 7 (Record Learnings and Update) as the primary mechanism for feeding improvements back into the skill set.
  • Curate and version: Keep skills in source control, name them clearly, and document when and why to use each one. Prefer small, composable skills over monolithic ones.

Skills References

References: