Yupeng Ma
← Back to projects

Case study

Yaya Loop

A feature-driven workflow for shipping software with AI coding agents and explicit human review.

Role · Creator and maintainer

  • AI Agents
  • Developer Tools
  • Python
  • Workflow
View Yaya Loop on GitHub ↗
A product specification becomes a bounded feature, an AI agent implements it, human review verifies the result, and the accepted change ships before the loop continues.

  1. 01

    Overview

    Context
    AI coding becomes difficult to control when product intent, task state, and completion rules live only in chat history.
    My contribution
    Designed the methodology, reusable document contracts, execution prompts, review gates, and project bootstrap workflow.
    Technology
    AI coding agents, Markdown, JSON, Python hooks, Git, and tool-specific adapters.
    Result
    Published a reusable v0.1 workflow kit and applied it to ongoing feature-by-feature project delivery.

  2. 02

    The Problem

    Longer AI-assisted projects can drift when requirements are scattered, agents change unrelated code, or implementation is treated as complete before automated and human validation.

  3. 03

    My Role

    Creator and maintainer

    • Designed the Product → Feature → Agent → Review → Ship execution loop.
    • Created reusable schemas, templates, prompts, coding-rule libraries, and completion gates.
    • Maintained AI-agnostic instructions alongside Claude Code integrations and Git-hook fallbacks.

  4. 04

    Architecture

    A focused map of the components and responsibility boundaries that matter to this project.

    Component map

    Versioned workflow architecture

    1. 01Product docs

      What the product should do

    2. 02Feature ledger

      Scope, dependencies, and status

    3. 03Coding rules

      Project-specific implementation constraints

    4. 04Execution prompts

      Repeatable steps for AI coding tools

    5. 05Quality gates

      Checks, human acceptance, and smell scan

    • Product docsFeature ledgerdecompose
    • Feature ledgerExecution promptsselect scope
    • Coding rulesExecution promptsconstrain
    • Execution promptsQuality gatesverify
    • Quality gatesFeature ledgerrecord state
    Product documents preserve intent, the feature ledger tracks bounded delivery state, coding rules constrain implementation, and execution prompts coordinate automated checks, human acceptance, and the completion gate. All four contracts live with the code so a new session can reconstruct the current state.

  5. 05

    How It Works

    The primary sequence that moves work or data through the system.

    Timeline / process

    Product-to-ship execution loop

    1. 01Product

      Versioned intent and constraints

    2. 02Feature

      One testable delivery slice

    3. 03AI agent

      Plan, implement, and self-check

    4. 04Review

      Automated and human gates

    5. 05Ship

      Record completion and continue

    • ProductFeaturedecompose
    • FeatureAI agentauthorize
    • AI agentReviewverify
    • ReviewShipaccept
    • ShipProductnext feature
    Versioned product intent is decomposed into one bounded feature. An AI agent implements the approved scope, automated checks and human review verify it, and only an accepted feature is marked complete before the next loop starts.

  6. 06

    Key Technical Decisions

    Problem
    Chat history is not a durable source of product intent or delivery state.
    Choice
    Keep product requirements, feature status, and coding constraints in versioned repository documents.
    Why
    Agents and humans can inspect the same source of truth across sessions, tools, and context resets.
    Trade-off
    The documents require deliberate maintenance as the product changes.
    Problem
    An AI agent can pass a code check without satisfying the product or the user.
    Choice
    Separate implementation, automated verification, human acceptance, and an independent smell scan before completion.
    Why
    Each gate answers a different question and prevents code completion from being mistaken for product completion.
    Trade-off
    The loop takes more steps than an unstructured prompt-and-commit workflow.

  7. 07

    Challenges

    • Keeping the workflow useful across new and existing projects without turning it into a heavyweight project-management system.
    • Expressing completion gates clearly enough for different AI tools to follow consistently.

  8. 08

    Outcome

    • Published methodology, templates, prompts, Claude Code adapters, Git hooks, and an end-to-end example under the MIT license.
    • Applied the workflow to this portfolio's feature-by-feature delivery with explicit human review.

  9. 09

    What I Learned

    Learned
    Versioned state, bounded features, and distinct validation gates are core design principles of the workflow.
    Reflection
    The repository separates reusable methodology from project-specific rules so adopters can tailor the workflow without changing its core loop.