Proposal: absorb useful feature-dev workflow patterns into agent-vault without losing canonical agent-vault memory

[ssheld]

Summary

The Anthropic feature-dev Claude Code plugin looks compatible enough with agent-vault to learn from, but not safe to treat as a peer workflow authority.

Unlike superpowers, it does not appear to create a parallel artifact tree or its own persistent spec/plan directories. The main risk is behavioral drift: an agent may follow feature-dev's phase workflow and subagent patterns while skipping or under-updating canonical agent-vault artifacts.

This issue proposes selectively absorbing the useful feature-dev workflow ideas into agent-vault while keeping agent-vault as the repo-owned source of truth.

Sources

• feature-dev README: https://github.com/anthropics/claude-plugins-official/blob/main/plugins/feature-dev/README.md
• feature-dev command: https://github.com/anthropics/claude-plugins-official/blob/main/plugins/feature-dev/commands/feature-dev.md
• feature-dev code-reviewer agent: https://github.com/anthropics/claude-plugins-official/blob/main/plugins/feature-dev/agents/code-reviewer.md
• agent-vault generated-project workflow rules: scaffold/agent-vault/AGENTS.md
• agent-vault shared rules: scaffold/agent-vault/shared-rules.md

What feature-dev Appears To Do Well

1. Stronger discovery / clarification gate

feature-dev explicitly asks clarifying questions before planning and implementation when the feature is underspecified.

This is useful for agent-vault because many multi-file feature requests fail not from weak coding but from weak upfront framing.

Potential value to import:

• detect ambiguity early
• require clarifying questions when requirements are underspecified
• reduce rework caused by premature implementation

2. Parallel codebase exploration before planning

The plugin uses a pattern like:

• launch multiple explorer agents
• inspect different parts of the codebase in parallel
• converge on the key files and architectural constraints before choosing an approach

That is stronger than a simple linear "read a few files and start coding" approach, especially in medium-size repos.

Potential value to import:

• better context-gathering before edits
• fewer shallow plans
• better architectural fit for cross-cutting changes

3. Architecture options with tradeoffs

feature-dev pushes toward selecting among multiple implementation approaches rather than jumping straight to one default path.

Examples of the style it encourages:

• minimal / low-risk option
• clean / more extensible option
• pragmatic / fastest acceptable option

Potential value to import:

• better up-front tradeoff reasoning
• clearer design decisions for reviewers
• better fit for non-trivial changes where multiple solutions are plausible

4. Built-in post-implementation review loop

The plugin includes a code-review phase after implementation instead of treating review as only something external humans do later.

Potential value to import:

• stronger self-critique before closeout
• earlier catch of regressions, missing docs, and missing tests
• better handoff quality before a PR is opened

5. Clear feature-work phases

feature-dev is more explicit than agent-vault about the lifecycle of non-trivial feature work:

• discovery
• exploration
• architecture selection
• implementation
• review
• summary

Potential value to import:

• a stronger execution mode for substantive feature work
• clearer expectations for when to pause and re-evaluate
• less improvisation between planning and coding

Where feature-dev Could Collide With agent-vault

This does not look like a storage-path collision like superpowers.

I do not see evidence that feature-dev creates its own persistent artifact tree like docs/superpowers/....

The collision risk is mostly workflow ownership.

1. It can become a second workflow controller

feature-dev defines its own ordered phases and approval expectations. If followed literally, those phases can override or displace agent-vault's repo-local workflow rules.

Relevant agent-vault rules already exist for:

• milestone planning in agent-vault/plan.md
• session start file reads
• session end memory updates
• design/doc consistency
• PR authoring and review response

If the plugin becomes the primary driver, agent-vault can become stale even if the code changes are good.

2. It does not appear to enforce agent-vault memory updates

agent-vault requires canonical repo memory updates for substantive work, including:

• agent-vault/context-log.md
• agent-vault/daily/YYYY-MM-DD.md
• agent-vault/design-log/YYYY-MM-DD-HHMM-<topic>.md
• decision records when durable decisions are made

feature-dev does not appear to know about those artifacts.

Risk:

• agents complete the feature-dev phases but leave project memory incomplete or stale

3. It uses ephemeral progress tracking rather than canonical project memory

The plugin uses TodoWrite-style progress tracking for execution.

That is fine as temporary working state, but it becomes a problem if agents treat that as the real plan instead of keeping agent-vault/plan.md and related artifacts current.

4. Its review step is generic, not agent-vault-native

The built-in review phase is useful in concept, but by itself it does not appear to enforce agent-vault's PR review formatting, attribution, fallback handling, or canonical response format.

Risk:

• decent review content, but non-canonical review packaging
• similar to the formatting drift already observed in generated-project reviews

5. Mandatory approval / ceremony could be too rigid for normal agent-vault use

One of agent-vault's strengths is that it can support both:

• substantial feature work
• small direct fixes without unnecessary ceremony

If feature-dev behavior is imported too literally, it could add too much friction to small tasks.

Honest Assessment

feature-dev looks much less dangerous than superpowers.

• superpowers behaved like a parallel memory/spec/plan system.
• feature-dev looks more like an opinionated feature-execution workflow.

That makes it a better donor for agent-vault.

The right move is probably:

• do not run feature-dev as a peer workflow authority in agent-vault repos
• do selectively absorb the best ideas into agent-vault's own rules

Proposal

Add an optional, repo-native Feature Development Mode to agent-vault for non-trivial feature work.

The key requirement is:

• agent-vault remains the canonical source of truth for plans, design notes, context, and decisions
• any imported feature-dev ideas must map into agent-vault artifacts rather than replacing them

Proposed Feature Development Mode

For substantive feature work, use a stronger staged workflow:

1. Discovery

• determine whether the request is underspecified
• ask clarifying questions when ambiguity would change the design

2. Codebase Exploration

• inspect relevant code paths in parallel where practical
• identify key files, constraints, and affected boundaries
• record the important findings in agent-vault/plan.md or a design-log note

3. Architecture Choice

• consider 2-3 plausible implementation options
• record tradeoffs briefly
• choose a recommended path
• update docs/design.md and/or agent-vault/project-context.md when architecture is affected

4. Implementation

• execute against the chosen approach
• keep milestone-level plan state in agent-vault/plan.md
• allow ephemeral todos, but do not let them replace canonical project memory

5. Review

• perform an explicit post-implementation self-review before closeout
• check correctness, docs consistency, validation completeness, and regressions
• ensure PR review output still follows agent-vault review policy

6. Summary / Session End

• update canonical agent-vault memory:
  • context-log.md
  • daily note
  • design-log note
  • decision record if needed
• ensure the branch/PR summary reflects the final implementation and validation state

Concrete Changes Worth Considering

1. Add a Feature Development Mode section to shared rules

Add a section to scaffold/agent-vault/shared-rules.md and mirrors that says:

• use this mode for non-trivial feature work
• small fixes do not need the full ceremony
• feature mode uses staged discovery / exploration / architecture / implementation / review / summary

2. Add a stronger clarification rule

Current agent-vault planning guidance could be enhanced to say:

• if ambiguity would materially change architecture, data model, APIs, rollout, or tests, ask clarifying questions before implementation

3. Strengthen plan expectations for feature work

Upgrade agent-vault/plan.md expectations to include:

• problem statement
• constraints
• relevant files/systems
• options considered
• recommended approach
• validation plan
• risks / rollback notes

4. Add a post-implementation self-review checkpoint

Before task closeout for substantive changes, require a quick explicit review pass that asks:

• does the implementation match the intended design?
• are docs consistent?
• are tests/validation sufficient?
• are there obvious regressions or open risks?

5. Clarify ephemeral vs canonical planning state

Add a rule like:

• temporary task trackers or todo tools are allowed
• they do not replace agent-vault/plan.md, context-log.md, daily notes, or design-log notes

6. Keep review output explicitly agent-vault-native

If feature-dev-style self-review is adopted, it should still feed into:

• canonical agent-vault PR review formatting
• canonical feedback-response format
• repo-owned review transport rules

What Not To Import

Do not import mandatory approval gates for all work

Forcing explicit user approval before implementation on every feature would likely slow down normal agent-vault usage too much.

Do not replace canonical artifacts with ephemeral tracking

TodoWrite or equivalent can be useful, but only as temporary working memory.

Do not make the full phase workflow mandatory for trivial fixes

agent-vault should preserve a lighter path for one-file fixes, straightforward docs work, and clearly bounded changes.

Do not make the feature workflow Claude-specific

Any absorbed pattern needs to remain compatible with Codex, Claude, and Gemini under repo-owned rules.

Suggested Acceptance Criteria

• agent-vault defines an optional Feature Development Mode for substantive feature work.
• The mode includes explicit stages for discovery, exploration, architecture choice, implementation, review, and summary.
• The policy clearly distinguishes temporary task tracking from canonical agent-vault memory.
• The mode reinforces that canonical project state still lives in agent-vault/* and docs/design.md.
• The mode keeps a lightweight path for trivial fixes.
• Future generated-project feature work benefits from stronger planning and review without creating a second workflow authority.

Questions for Review

• Should Feature Development Mode live in shared-rules.md, a separate section of AGENTS.md, or a standalone generated template?
• Should the clarification gate be mandatory for all non-trivial work, or only when architectural ambiguity is present?
• Should agent-vault/plan.md be updated as a template, or should the stronger structure live only in policy text?
• Should a self-review checkpoint be mandatory before PR creation for substantial changes?
• Is a helper template for feature-mode plans worth adding, or is policy text enough?

Related Context

This is similar in spirit to the earlier superpowers discussion, but importantly different:

• superpowers created a stronger risk of parallel artifact trees and duplicate sources of truth
• feature-dev looks more like a reusable execution workflow whose best parts can be adapted into agent-vault

That makes this proposal less about compatibility shims and more about improving agent-vault's own feature-development ergonomics.