Making AgentFlow Changes

When to Use This Skill

Load this skill when you need to:

• Edit AgentFlow framework files in the source repository (/srv/worktrees/agentflow/main/)
• Fix or improve AgentFlow framework files (agents, skills, docs, scripts)
• Contribute changes from a consumer project back to AgentFlow
• Update the CHANGELOG and manage versions
• Understand the "edit in client, sync back" workflow
• Commit any changes to .claude/ or .agentflow/ directories

Rules (FOLLOW THESE)

Contribution Rules

1. MUST make framework changes in the AgentFlow worktree (/srv/worktrees/agentflow/main/)
2. MUST update CHANGELOG.md under [Unreleased] for every change
3. MUST follow Keep a Changelog format (Added, Changed, Fixed, Removed, Deprecated, Security)
4. SHOULD test changes in a consumer project before committing to AgentFlow
5. MUST run /af:push after committing to distribute changes to all consumer worktrees

Commit Rules

6. MUST use conventional commit format: type(scope): description
7. MUST include framework: or af: in scope for framework changes
8. SHOULD reference the consumer project that discovered the issue
9. MUST NOT commit directly to consumer projects' framework files

File Location Rules

10. AgentFlow source: /srv/worktrees/agentflow/main/
11. Consumer projects: /srv/worktrees/{project}/main/ or /data/worktrees/{project}/{branch}/
12. MUST edit in AgentFlow source, then sync to consumers

Version Bump Rules (Periodic, Not Per-Change)

13. Version bumps are optional - do them monthly or for breaking changes
14. PATCH (x.x.1) - Bug fixes, typo corrections, minor doc updates
15. MINOR (x.1.0) - New features, new skills/agents, non-breaking improvements
16. MAJOR (1.0.0) - Breaking changes, architecture changes, removed features

What Gets Synced vs Preserved

Understanding which files are synced from AgentFlow is critical. Synced files will be overwritten on the next /af:sync - any local changes will be lost.

Synced (Overwritten on Sync)

These files come from AgentFlow and MUST be edited in /srv/worktrees/agentflow/main/:

Preserved (Safe to Edit Locally)

These files are never touched by sync - edit them directly in your project:

Quick Rule

af- prefix = Framework owned = Edit in AgentFlow source No af- prefix = Project owned = Edit locally

Workflows

Workflow: Edit in Client, Sync Back

When: You discover a framework issue or improvement while working in a consumer project

Steps:

1. Identify the change in the consumer project (e.g., stale doc, bug, missing feature)

2. Switch to AgentFlow worktree:

   bashCopy

   cd /srv/worktrees/agentflow/main
   

3. Make the change to the framework file(s)

4. Update CHANGELOG.md under [Unreleased]:

   markdownCopy

   ## [Unreleased]
   
   ### Fixed
   - **Stale BDD Guide** - Removed outdated Gherkin documentation that conflicted with V2 Markdown scenario approach
   

5. Commit the change:

   bashCopy

   git add .
   git commit -m "fix(af:docs): remove stale bdd-guide.md
   
   Gherkin was deprecated in V2 in favor of Markdown scenarios.
   The old guide was causing confusion in docs audits.
   
   Discovered in: XTL project"
   

6. Push to AgentFlow remote (if applicable)

7. Preview broadcast — read CHANGELOG.md [Unreleased] section and present to the user:

   Copy

   These changes will be broadcast to all projects:
   
   Fixed:
   - Stale BDD Guide
   Changed:
   - BDD Agent output format
   Added:
   - Making AgentFlow Changes Skill
   
   Last release: v3.1.0 (2026-01-26)
   Suggestion: v3.2.0 (minor — new features added)
   
   Bump version before pushing? [yes / no / custom version]
   

   STOP and wait for the user's decision.

8. If version bump approved:

   • Move [Unreleased] entries to new version section in CHANGELOG.md
   • Add empty [Unreleased] section
   • Update version in template-manifest.json
   • Commit: chore(af:release): v{VERSION}
   • Tag: git tag v{VERSION}

   If no version bump: Skip to step 9.

9. Push to all consumer worktrees:

   bashCopy

   npx ts-node .claude/scripts/sync/push-to-projects.ts
   

   This syncs to all worktrees across all projects and auto-commits the changes.

10. Broadcast to Zulip — read .claude/work/push-notifications.jsonl and post one message per project stream on Zulip. The notification includes the CHANGELOG summary (see Zulip Notification section below).

Success criteria:

• Change is in AgentFlow source (not just consumer)
• CHANGELOG updated
• User chose whether to version bump (or not)
• All consumer worktrees synced via /af:push
• Teams notified via Zulip

Note: /af:sync is still available for ad-hoc use (e.g., syncing a newly created branch that /af:push hasn't seen yet).

Workflow: Version Bump and Release (Optional/Periodic)

When: Monthly, or when making breaking changes. Not required for every change.

Steps:

1. Review [Unreleased] section in CHANGELOG.md
2. Determine version bump type:
   • Bug fixes only → PATCH (2.1.0 → 2.1.1)
   • New features → MINOR (2.1.0 → 2.2.0)
   • Breaking changes → MAJOR (2.1.0 → 3.0.0)
3. Update CHANGELOG.md:
   markdownCopy

   ## [Unreleased]
   
   _No unreleased changes_
   
   ---
   
   ## [2.2.0] - 2026-01-03
   
   ### Added
   - **Making AgentFlow Changes Skill** - Documents contribution workflow
   
   ### Fixed
   - **Stale BDD Guide** - Removed outdated Gherkin documentation
   

4. Update version in template-manifest.json:
   jsonCopy

   {
     "version": "2.2.0"
   }
   

5. Commit the release:
   bashCopy

   git add CHANGELOG.md template-manifest.json
   git commit -m "chore(af:release): v2.2.0"
   git tag v2.2.0
   

6. Push with tags:
   bashCopy

   git push && git push --tags
   

Workflow: Fixing Stale Documentation

When: Documentation doesn't match current implementation

Steps:

1. Identify the stale doc (e.g., audit finds outdated guide)
2. Determine action:
   • Doc still relevant but outdated → Update it
   • Doc describes deprecated approach → Delete it
   • Doc partially correct → Edit specific sections
3. Switch to AgentFlow worktree:
   bashCopy

   cd /srv/worktrees/agentflow/main
   

4. Make the fix:
   • If deleting: git rm .claude/docs/guides/stale-guide.md
   • If updating: Edit the file with correct information
5. Update parent README if file was deleted (remove from children array)
6. Update CHANGELOG:
   markdownCopy

   ### Fixed
   - **Stale {Guide Name}** - {Brief description of fix}
   

   OR
   markdownCopy

   ### Removed
   - **{Guide Name}** - Deprecated in V2, replaced by {new approach}
   

7. Commit and sync (per Workflow: Edit in Client, Sync Back)

Workflow: Adding New Framework Component

When: Creating a new agent, skill, command, or doc

Steps:

1. Switch to AgentFlow worktree
2. Load af-agentflow-framework-development skill for templates and standards
3. Create the component following namespace rules (af- prefix)
4. Update parent README with new child reference
5. Update CHANGELOG:
   markdownCopy

   ### Added
   - **{Component Name}** in `{location}`
     - {Bullet point describing what it does}
     - {Another bullet if needed}
   

6. Test the component in a consumer project if possible
7. Commit with descriptive message:
   bashCopy

   git commit -m "feat(af:skills): add af-making-agentflow-changes skill
   
   Documents the contribution workflow for editing framework
   files in consumer projects and syncing back.
   
   - Covers version bumping rules
   - Covers CHANGELOG format
   - Covers commit standards"
   

Examples

Good CHANGELOG Entry

## [2.2.0] - 2026-01-03

### Added
- **Making AgentFlow Changes Skill** (`af-making-agentflow-changes`)
  - Documents "edit in client, sync back" workflow
  - Covers version bumping and CHANGELOG standards
  - Includes commit message conventions

### Fixed
- **Stale BDD Guide** - Removed `.claude/docs/guides/bdd-guide.md` which documented deprecated Gherkin approach (V2 uses Markdown scenarios)

### Changed
- **BDD Agent** - Updated to clarify V2 Markdown scenario output format

Good Commit Messages

# Feature addition
git commit -m "feat(af:skills): add email testing patterns to af-testing-expertise"

# Bug fix
git commit -m "fix(af:docs): remove stale bdd-guide.md

Gherkin deprecated in V2, guide was causing audit confusion.
Discovered in: XTL project"

# Documentation update
git commit -m "docs(af:guides): update framework-sync with contribution workflow"

# Breaking change
git commit -m "feat(af:agents)!: rename af-search-agent to af-web-search-agent

BREAKING CHANGE: Agent name changed, update Task tool invocations"

Bad Practices

# Bad: No context
### Fixed
- Fixed a bug

# Bad: Not using Keep a Changelog categories
### Updates
- Made some changes to the BDD stuff

# Bad: Mixing concerns
### Added
- New skill and also fixed that doc and changed some things

Zulip Notification

After running /af:push, the push script generates notification entries in .claude/work/push-notifications.jsonl. Post one message per project stream on Zulip using the bot credentials.

Notification format (one per project channel):

:arrows_counterclockwise: AgentFlow v{VERSION} pushed to {PROJECT}

What changed:
- {Bold headline from each CHANGELOG entry}
- {Another entry}

Changes auto-committed. Run `git log -1` in any worktree to review.

The push script automatically extracts the CHANGELOG summary. Read the entries from .claude/work/push-notifications.jsonl and post each one to its channelId.

For breaking changes, also announce to #engineering-team on Zulip:

:warning: AgentFlow v{VERSION} pushed - BREAKING CHANGE

{description of breaking change and required action}

All worktrees have been updated automatically.

Note: /af:sync is still available for projects to manually pull updates (e.g., for newly created branches).

Essential Reading

Related skills:

• AgentFlow Framework Development - Creating components

Sync documentation:

• Framework Sync Guide - How sync works
• /af:push Command - Push distribution command
• /af:sync Command - Pull sync command (ad-hoc use)

Standards:

• Keep a Changelog - CHANGELOG format
• Semantic Versioning - Version numbering
• Conventional Commits - Commit format

Remember:

1. Always edit in AgentFlow source, not consumer projects
2. Always update CHANGELOG under [Unreleased]
3. After committing, preview the CHANGELOG and ask the user about version bumping before pushing
4. Always run /af:push after committing to distribute to all worktrees
5. Post one Zulip notification per project stream with CHANGELOG summary
6. Push works on any branch - feature branches are fine
7. Version bumps are optional - do them monthly or for breaking changes
8. /af:sync still works for ad-hoc pull (new branches, targeted sync)