agentleFS
Sign inStart free
jmxt3jmxt3/gitscape.ai/.agents/skills/incremental-implementation/SKILL.md

incremental-implementation

Skill33 starsChanged 4 months agoApache-2.0View on GitHub

Delivers changes incrementally. Use when implementing any feature or change that touches more than one file. Use when you're about to write a large amount of code at once, or when a task feels too big to land in one step.

We split this skill into the rules it gives an agent

14 rules. 0 are common, 14 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 69 edited versions we read keep these.

  • 14

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When you're tempted to "just write it all out first and then test"

    line 16
  2. Distinctive:

    Read the task's acceptance criteria

    line 27
  3. Distinctive:

    Write a test that describes the expected behavior.

    line 36
  4. Distinctive:

    If the test passes before you write the implementation, the test is wrong.

    line 47
  5. Distinctive:

    Write only the code needed to make the test pass.

    line 51
  6. Distinctive:

    Follow existing patterns in the codebase

    line 53
  7. Distinctive:

    No adding features that aren't in the acceptance criteria

    line 56
  8. Distinctive:

    All existing tests must pass.

    line 65
  9. Distinctive:

    Ensure the project builds/compiles cleanly:

    line 69
  10. Distinctive:

    Update the task list and stop.

    line 96
  11. Distinctive:

    When adding new behavior, default to the current behavior and opt into new behavior:

    line 119
  12. Distinctive:

    Every commit should be revertable with git revert without taking down the system:

    line 135
  13. Distinctive:

    Never combine schema changes with behavior changes in one commit

    line 137
  14. Distinctive:

    Never remove a field that other services still read — add the replacement first, migrate, then remove

    line 138

“Common” is measured: kept by at least 6 in 10 of the 69 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Incremental Implementation

Overview

Ship thin vertical slices: implement, test, verify, commit — one task at a time. Never write a large batch of changes all at once. Each increment should leave the system in a working, deployable state. This protects against regressions, makes reviews easier, and provides clean rollback points.

When to Use

  • Any change touching more than one file
  • Implementing a task from an existing plan
  • When you're tempted to "just write it all out first and then test"
  • Any feature that takes more than one focused session to implement

When NOT to use: Single-line typo fixes or isolated config changes with no behavior impact.

The Increment Loop

For every task, follow this exact loop:

1. Read Before Writing

  • Read the task's acceptance criteria
  • Load the relevant existing code (the files this task touches)
  • Identify the pattern being extended, not invented
  • Confirm the approach matches the spec

Stop if: The approach differs significantly from the spec. Update the spec or plan first.

2. Write a Failing Test (RED)

Write a test that describes the expected behavior. The test must fail before you write any implementation code.

# Example for a FastAPI endpoint
def test_export_skill_returns_zip():
    """Skill export endpoint should return a valid zip file."""
    response = client.post("/api/skills/export", json={"repo": "owner/repo"})
    assert response.status_code == 200
    assert response.headers["content-type"] == "application/zip"

If the test passes before you write the implementation, the test is wrong. Fix it.

3. Implement the Minimum (GREEN)

Write only the code needed to make the test pass. No more, no less.

  • Follow existing patterns in the codebase
  • No premature abstractions
  • No "while I'm here" refactors
  • No adding features that aren't in the acceptance criteria

4. Run All Tests

pytest tests/ -v              # full suite
pytest tests/ -k "test_name"  # targeted run for the new test

All existing tests must pass. If they don't, fix the regression before proceeding.

5. Build Check

Ensure the project builds/compiles cleanly:

# Python: check imports resolve
python -c "from api.app import create_app"
# TypeScript/JS: type check
npx tsc --noEmit

6. Commit

One commit per task. Stage only the files that task touched:

git add api/app/path/to/changed_file.py tests/test_changed.py
git commit -m "feat(skills): add zip export endpoint for skill download

- POST /api/skills/export accepts {repo: string}
- Returns application/zip with SKILL.md and supporting files
- Validates repo exists before building archive

Closes #42"

Never git add -A blindly — it absorbs unrelated local work and breaks clean rollback.

7. Mark the Task Complete and Stop

Update the task list and stop. Do not immediately start the next task. Present the result for human review if the task was Medium or larger.

Feature Flags

For high-risk changes that must be deployed before they are activated:

# api/app/config.py
FEATURE_FLAGS = {
    "skill_hd_tier": os.getenv("FF_SKILL_HD_TIER", "false").lower() == "true",
}

# Usage
if settings.FEATURE_FLAGS["skill_hd_tier"]:
    return generate_hd_skill(repo)
else:
    return generate_standard_skill(repo)

Deploy with FF_SKILL_HD_TIER=false, enable via env var when ready.

Safe Defaults

When adding new behavior, default to the current behavior and opt into new behavior:

# BAD: new behavior is default, breaks existing users
def generate_skill(repo, format="enhanced"):
    ...

# GOOD: existing behavior is default
def generate_skill(repo, format="standard"):
    if format == "enhanced" and feature_flags.hd_tier:
        return _generate_enhanced(repo)
    return _generate_standard(repo)

Rollback-Friendly Changes

Every commit should be revertable with git revert without taking down the system:

  • Never combine schema changes with behavior changes in one commit
  • Never remove a field that other services still read — add the replacement first, migrate, then remove
  • Database migrations go in their own commit, run before the code that depends on them

Common Rationalizations

RationalizationReality
"I'll test at the end when it's all done"By then, failures are hard to localize. Test each slice so failures are obvious.
"The test is trivial for this part"Write it anyway. Trivial tests catch trivial regressions.
"I can see how it fits together — just let me write it all"You'll produce a 400-line diff that no one can review, with a bug buried on line 312.
"Refactoring this first will make the feature easier"Refactor in a separate commit before the feature. Never mix.

Red Flags

  • A commit with more than ~200 lines changed (sign of too-big slices)
  • A commit message with "WIP", "stuff", or "various changes"
  • Implementation written before the test
  • Committing git add -A without reviewing what's staged
  • "It works on my machine" as the only verification

Verification

After each increment:

  • A failing test was written first
  • The test now passes
  • The full test suite passes (no regressions)
  • The build is clean
  • The commit is atomic (only files from this task)
  • The commit message describes what and why
  • The system is in a deployable state at this commit

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free