feature-marker

Category: Tools & Productivity | Uploader: Viniciuscarvalho | Downloads: 0 | Version: v1.0（Latest）

Platform-agnostic workflow automation with checkpoints (PRD/TechSpec/Tasks generation + implementation + tests + commit/PR).

Changelog: Source: GitHub https://github.com/Viniciuscarvalho/Feature-marker

Directory Structure

Current level: feature-marker-dist/feature-marker/

📁 lib/
- 📄 config.sh 2.1 KB
- 📄 dependency-installer.sh 6.6 KB
- 📄 mcp-detector.sh 10.5 KB
- 📄 menu.sh 10.7 KB
- 📄 platform-detector.sh 2.1 KB
- 📄 spec-workflow-bridge.sh 8.1 KB
- 📄 stack-detector.sh 14.8 KB
- 📄 state-manager.sh 4.4 KB
- 📄 ui.sh 3.2 KB
📁 references/
- 📁 mcp-adapters/
  - 📄 docker.md 1.4 KB
  - 📄 playwright.md 2.4 KB
  - 📄 xcodebuild.md 2.3 KB
- 📁 stack-patterns/
  - 📄 python.md 3.1 KB
  - 📄 react.md 3.3 KB
  - 📄 swift.md 3.5 KB
📁 resources/
- 📁 spec-workflow/
  - 📁 personas/
    
    📄 api-security-reviewer.md 2.8 KB
    
    📄 data-migration-reviewer.md 3.0 KB
    
    📄 firebase-cost-reviewer.md 2.3 KB
    
    📄 ios-performance-reviewer.md 2.6 KB
    
    📄 payment-flow-reviewer.md 3.1 KB
  - 📁 references/
    
    📄 config.md 7.1 KB
    
    📄 personas.md 6.7 KB
    
    📄 spec-template.md 3.5 KB
    
    📄 spec-writer-integration.md 4.1 KB
  - 📁 skills/
    
    📁 ac-lock/
    
    📄 SKILL.md 6.8 KB
    
    📁 context-gatherer/
    
    📄 SKILL.md 6.8 KB
    
    📁 create-worktree/
    
    📄 SKILL.md 3.7 KB
    
    📁 idea-explorer/
    
    📄 SKILL.md 8.7 KB
    
    📁 ios-workflow/
    
    📄 SKILL.md 8.6 KB
    
    📁 platform-detection/
    
    📄 SKILL.md 5.2 KB
    
    📁 prd-validator/
    
    📄 SKILL.md 8.4 KB
    
    📁 prompt-enricher/
    
    📄 SKILL.md 7.3 KB
    
    📁 spec-executor/
    
    📄 SKILL.md 16.0 KB
    
    📁 spec-orchestrator/
    
    📄 SKILL.md 11.5 KB
    
    📁 spec-workflow-init/
    
    📄 SKILL.md 9.7 KB
    
    📁 spec-writer/
    
    📄 SKILL.md 12.6 KB
    
    📁 tasks-validator/
    
    📄 SKILL.md 9.7 KB
    
    📁 techspec-validator/
    
    📄 SKILL.md 10.1 KB
    
    📁 test-only/
    
    📄 SKILL.md 8.4 KB
  - 📄 ABSTRACTION_PLAN.md 20.9 KB
  - 📄 PROJECT-template.md 2.6 KB
  - 📄 README.md 3.7 KB
- 📄 commit.md 9.7 KB
📁 scripts/
- 📄 discover-env.sh 5.6 KB
📁 templates/
- 📄 prd-template.md 936 B
- 📄 techspec-template.md 1.5 KB
📄 .DS_Store 6.0 KB
📄 feature-marker.sh 7.6 KB
📄 install.sh 5.0 KB
📄 SKILL.md 17.2 KB

SKILL.md

---
name: feature-marker
description: Platform-agnostic workflow automation with checkpoints (PRD/TechSpec/Tasks generation + implementation + tests + commit/PR).
tools: Read, Write, Edit, Grep, Glob, Bash, TodoWrite, Skill
---

# feature-marker

Automates feature development with a 5-phase workflow:

1. **Inputs Gate** - Validates `prd.md`, `techspec.md`, `tasks.md` exist; generates them via `~/.claude/commands/` if missing.
2. **Analysis & Planning** - Auto-installs product-manager skill if missing; reads docs, creates implementation plan.
3. **Implementation** - Executes tasks with progress tracking.
4. **Tests & Validation** - Runs platform-appropriate test suites and build validation.
   Auto-detects: Swift/Xcode (+ XcodeBuildMCP simulator), Node.js, Rust, Python, Go.
5. **Commit & PR** - Auto-installs enhanced commit command if missing; commits changes using professional workflow and creates PR (auto-detects git platform).

## Platform Support

feature-marker works with any tech stack:

- 🍎 **iOS/Swift** — `swift test` + SwiftLint + XcodeBuildMCP simulator validation
- 🟨 **Node.js/TypeScript** — auto-detects npm/yarn/pnpm/bun + Jest/Vitest
- 🦀 **Rust** — `cargo test` + `cargo clippy`
- 🐍 **Python** — `pytest` + ruff/flake8
- 🐹 **Go** — `go test` + `go vet`

iOS/Xcode projects get additional simulator validation via XcodeBuildMCP (optional, non-blocking).
The platform is auto-detected once at workflow start and cached — no configuration required.

### MCP-Enhanced Validation

When MCP servers are detected in agent config files, feature-marker loads adapter references to enhance validation:

| MCP           | Category   | Enhancement                                  |
| ------------- | ---------- | -------------------------------------------- |
| XcodeBuildMCP | build      | Simulator build verification after iOS tasks |
| Playwright    | test       | E2E browser testing and visual regression    |
| Docker        | deployment | Container build verification                 |

MCP failures are always **non-blocking** — CLI fallback is the primary path; MCPs enhance, never gate.

## Environment Awareness

feature-marker automatically discovers the full development environment:

1. **Stack detection** (`lib/stack-detector.sh`) — identifies platform, test runner, package manager
2. **MCP detection** (`lib/mcp-detector.sh`) — scans agent config files for configured MCP servers
3. **CLI detection** — checks PATH for available development tools
4. **CI detection** — identifies CI/CD configuration

All results are merged into `environment_manifest.json` via `scripts/discover-env.sh`.

### MCP Detection

Scans these config files for MCP server definitions:

- `.claude/settings.json` (project) + `~/.claude/settings.json` (global)
- `.cursor/mcp.json`
- `.codex/config.toml`
- `~/Library/Application Support/Claude/claude_desktop_config.json`
- `.vscode/settings.json`
- `.kiro/settings/mcp.json`

Detected MCPs are classified by category (build, test, database, deployment, project-mgmt) and matched to adapter references in `references/mcp-adapters/`.

### Adapter Loading (Lazy)

Adapters are markdown files in `references/mcp-adapters/` that tell Claude HOW to use each MCP in each feature-marker phase. They are loaded **only when that MCP is detected** — keeping the context window small.

Available adapters:

- `xcodebuild.md` — Xcode project discovery, build, simulator
- `playwright.md` — browser E2E testing and screenshots
- `docker.md` — container build verification

### Stack Pattern References

Stack-specific conventions are loaded from `references/stack-patterns/` when that stack is detected:

- `swift.md` — MVVM/Clean Architecture, Swift Testing, error handling
- `react.md` — Component/Hook/Service layering, React Testing Library
- `python.md` — pytest fixtures, type hints, FastAPI/Django patterns

### Phase 0 Behavior

When the workflow starts, before Phase 1:

1. Run `scripts/discover-env.sh` to generate `environment_manifest.json`
2. Read the manifest to identify detected MCPs and stack
3. Load matching adapter references for detected MCPs
4. Load matching stack pattern reference for detected platform
5. Pass environment context to context-gatherer and prompt-enricher

## Usage

```
/feature-marker <feature-slug>
```

**Example**:

```
/feature-marker prd-user-authentication
```

### Interactive Mode

```
/feature-marker --interactive <feature-slug>
```

Opens a menu to select execution mode:

- **Full Workflow** - Default, generates missing files and executes all phases
- **Tasks Only** - Uses existing files, skips generation phase
- **Ralph Loop** - Autonomous continuous execution with ralph-wiggum
- **Spec-Driven** - Multi-agent review + worktree isolation via spec-workflow
- **Test Only** - Runs tests phase exclusively using platform-appropriate test guidance (Swift Testing for iOS, Jest/Vitest for Node.js, etc.)

Works both in terminal (TTY menu) and Claude CLI (AskUserQuestion prompt).

**Direct mode selection** (skip menu):

```
/feature-marker --mode full <feature-slug>
/feature-marker --mode tasks-only <feature-slug>
/feature-marker --mode ralph-loop <feature-slug>
/feature-marker --mode spec-driven <feature-slug>
/feature-marker --mode test-only <feature-slug>
```

## Prerequisites

### Commands

The following commands must be available in `~/.claude/commands/`:

- `create-prd.md` - Creates a new PRD from requirements discussion
- `generate-spec.md` - Generates technical specification from PRD
- `generate-tasks.md` - Breaks down feature spec into implementable tasks

### Templates

The commands above read templates from `~/.claude/docs/specs/` to generate structured documents.

Required templates:

- `~/.claude/docs/specs/prd-template.md` - Product Requirements Document template
- `~/.claude/docs/specs/techspec-template.md` - Technical Specification template
- `~/.claude/docs/specs/tasks-template.md` - Tasks breakdown template

**Template Format**: Templates should be markdown files with placeholders and structure that commands will use to generate feature-specific documents.

**Setup**: Ensure these templates exist before running feature-marker:

```bash
ls ~/.claude/docs/specs/
# Should show: prd-template.md, techspec-template.md, tasks-template.md
```

**Bundled Fallback**: If user templates are missing, feature-marker includes bundled templates in `templates/` that will be used as fallback:

- `templates/prd-template.md` — basic PRD structure
- `templates/techspec-template.md` — basic tech spec structure

User templates in `~/.claude/docs/specs/` always have priority over bundled versions.

### Project Structure

**Feature Documents** (generated in project):

```
./tasks/
└── prd-{feature-name}/
    ├── prd.md            ← Generated from ~/.claude/docs/specs/prd-template.md
    ├── techspec.md       ← Generated from ~/.claude/docs/specs/techspec-template.md
    ├── tasks.md          ← Generated from ~/.claude/docs/specs/tasks-template.md
    └── {num}_task.md     ← Individual task files (optional)
```

**State Directory** (checkpoint & progress):

```
.claude/feature-state/{feature-name}/
├── checkpoint.json
├── analysis.md
├── plan.md
├── progress.md
├── test-results.md
└── pr-url.txt
```

**User Configuration** (required setup):

```
~/.claude/
├── commands/           ← Commands that generate files
│   ├── create-prd.md
│   ├── generate-spec.md
│   └── generate-tasks.md
└── docs/
    └── specs/          ← Templates used by commands
        ├── prd-template.md
        ├── techspec-template.md
        └── tasks-template.md
```

## Behavior

When invoked, the skill:

1. **Validates inputs** - Checks if `./tasks/prd-{feature-slug}/` contains required files
   - If all files exist → Skips to step 3
   - If any file is missing → Proceeds to step 2
2. **Generates ONLY missing files** - Existing files are never overwritten:
   - Missing PRD → `/create-prd`
   - Missing Tech Spec → `/generate-spec {feature-slug}`
   - Missing Tasks → `/generate-tasks {feature-slug}`
3. **Auto-installs missing dependencies**:
   - **Phase 1**: Checks for `product-manager` skill
     - If missing: Installs via `npx skills add https://github.com/aj-geddes/claude-code-bmad-skills --skill product-manager`
     - If user already has it: Uses user's version
     - If installation fails: Continues without it (non-blocking)
   - **Phase 4**: Checks for `/commit` command
     - If missing: Copies from bundled `resources/commit.md` to `~/.claude/commands/commit.md`
     - If user already has it: Uses user's version
     - If installation fails: Falls back to standard commit workflow
4. **Executes 5-phase workflow** via the `feature-marker` agent
5. **Persists state** - Saves checkpoints after each phase/task for resume capability

**Important**: The workflow is smart about file detection and dependencies:

- ✅ Files/skills/commands exist → Uses them directly, no regeneration or reinstallation
- ⚠️ Missing → Installs/generates only what's needed
- 🔒 Never overwrites existing content
- 👤 **User's versions always have priority** over bundled/auto-installed versions

## Auto-Installed Dependencies

Feature-marker automatically installs missing dependencies to enhance the workflow:

### Product Manager Skill (Phase 1)

**What it does**: Provides advanced PRD analysis, requirements validation, and product management capabilities.

**Installation**:

- **Check**: Phase 1 checks for `~/.claude/skills/product-manager/SKILL.md`
- **Install**: If missing and `npx` available, runs:
  ```bash
  npx skills add https://github.com/aj-geddes/claude-code-bmad-skills --skill product-manager
  ```
- **Priority**: Uses user's existing skill if already installed
- **Fallback**: Continues without it if installation fails (non-blocking)

**Benefits**:

- Enhanced requirement analysis
- Better PRD validation
- Improved feature planning

### Enhanced Commit Command (Phase 4)

**What it does**: Professional commit workflow with validation, splitting, and conventional commit format.

**Installation**:

- **Check**: Phase 4 checks for `~/.claude/commands/commit.md`
- **Install**: If missing, copies from bundled `resources/commit.md` to `~/.claude/commands/commit.md`
- **Priority**: Uses user's existing command if already installed
- **Fallback**: Uses standard commit workflow if installation fails

**Features**:

- Pre-commit validation (lint, build, docs)
- Intelligent commit splitting
- Conventional commit format with emojis
- Smart file staging
- No Co-Authored-By footer (as per command design)

**Example Output**:

```bash
✨ feat: add user authentication system
🐛 fix: resolve memory leak in rendering process
📝 docs: update API documentation
♻️ refactor: simplify error handling logic
```

### Manual Installation

If auto-installation fails, you can install manually:

**Product Manager Skill**:

```bash
npx skills add https://github.com/aj-geddes/claude-code-bmad-skills --skill product-manager
```

**Commit Command**:

```bash
cp ~/.claude/skills/feature-marker/resources/commit.md ~/.claude/commands/commit.md
```

## Template Setup Guide

### Template Directory Structure

Commands in `~/.claude/commands/` read templates from a centralized location:

```
~/.claude/docs/specs/
├── prd-template.md          # Product Requirements Document template
├── techspec-template.md     # Technical Specification template
└── tasks-template.md        # Task breakdown template
```

### Why Templates in ~/.claude/docs/specs?

- **Centralized**: All projects share the same templates
- **User-controlled**: Users can customize their own templates
- **Portable**: Commands reference templates via standard path
- **Separation**: Templates are not in project repositories

### Template Content

Each template should be a markdown file with:

- Clear section structure
- Placeholder text or variables
- Examples and formatting guidelines

Commands read these templates and populate them with feature-specific content.

### Setup Verification

To verify your setup is complete:

```bash
# Check templates exist
ls -l ~/.claude/docs/specs/

# Check commands exist
ls -l ~/.claude/commands/

# Test feature-marker
/feature-marker --interactive prd-test-feature
```

If templates are missing, create them in `~/.claude/docs/specs/` before running feature-marker.

## Plan Mode Integration

When the user has used Claude's built-in plan mode before invoking feature-marker, the agent automatically:

1. **Detects the most recent plan** from `~/.claude/plans/` (sorted by modification time)
2. **Reads project conventions** from `./CLAUDE.md` at the project root (if present)
3. **Uses both as rich context** to enhance PRD generation and reduce redundant clarification questions

This is automatic and requires no additional flags or options. If no plan or CLAUDE.md exists, the workflow proceeds normally.

**Recommended flow**:

```
1. Use Claude plan mode to explore the codebase and think through the feature
2. Exit plan mode
3. Run /feature-marker --interactive <feature-slug>
4. Select "Full Workflow"
5. The plan content automatically enriches PRD generation
```

## Checkpoint & Resume

If interrupted (Ctrl+C, session crash, etc.), re-invoke with the same feature slug to resume:

```
/feature-marker prd-user-authentication
```

The skill will:

- Detect existing checkpoint
- Show current progress (phase, task index)
- Ask if you want to resume or start fresh

## Platform Detection

In Phase 4, the skill auto-detects your git platform and selects the appropriate PR skill:

| Platform     | Detection                     | PR Skill      |
| ------------ | ----------------------------- | ------------- |
| GitHub       | `github.com` in remote URL    | `checking-pr` |
| Azure DevOps | `dev.azure.com` in remote URL | `azure-pr`    |
| GitLab       | `gitlab.com` in remote URL    | `checking-pr` |
| Bitbucket    | `bitbucket.org` in remote URL | `checking-pr` |
| Other        | (fallback)                    | `checking-pr` |

## Configuration

Override default behavior with `.feature-marker.json` in your repository root:

```json
{
  "pr_skill": "custom-pr-skill",
  "skip_pr": false,
  "test_command": "npm run test:ci",
  "docs_path": "./tasks",
  "state_path": ".claude/feature-state"
}
```

## Error Handling

| Scenario             | Behavior                              |
| -------------------- | ------------------------------------- |
| Missing files        | Auto-generate via commands            |
| No git repo          | Fail early with helpful message       |
| No tests             | Skip Phase 3 with warning             |
| Test failures        | Report issues, allow fix, offer retry |
| Unknown platform     | Fallback to `checking-pr`             |
| PR skill unavailable | Commit only, log manual instructions  |

## Example Sessions

### Example 1: All Files Exist (No Generation Needed)

```
> /feature-marker prd-user-authentication

Checking for existing checkpoint...
No checkpoint found. Starting new workflow.

Phase 0: Inputs Gate
✓ prd.md exists
✓ techspec.md exists
✓ tasks.md exists
✅ All files present. Skipping generation.

Phase 1: Analysis & Planning
Reading existing documents...
Creating implementation plan...
Checkpoint saved.

Phase 2: Implementation
[1/6] Create User entity... ✓
[2/6] Add authentication service... ✓
...
```

### Example 2: Partial Files (Generates Only Missing)

```
> /feature-marker prd-payment-integration

Checking for existing checkpoint...
No checkpoint found. Starting new workflow.

Phase 0: Inputs Gate
✓ prd.md exists
✗ techspec.md missing → Generating via /generate-spec...
✓ tasks.md exists

✅ Generated missing file. All inputs ready.

Phase 1: Analysis & Planning
Reading documents...
Creating implementation plan...
Checkpoint saved.
...
```

### Example 3: Complete Workflow with Auto-Install

```
> /feature-marker prd-new-feature

Phase 0: Inputs Gate
✗ prd.md missing → Generating via /create-prd...
✗ techspec.md missing → Generating via /generate-spec...
✗ tasks.md missing → Generating via /generate-tasks...

Phase 1: Analysis & Planning
⚙️  Installing product-manager skill...
✓ product-manager skill installed successfully
Reading PRD, Tech Spec, and Tasks...
Creating implementation plan...
Checkpoint saved.

Phase 2: Implementation
[1/6] Create User entity... ✓
[2/6] Add authentication service... ✓
[3/6] Implement login endpoint... ✓
[4/6] Add JWT token handling... ✓
[5/6] Create logout endpoint... ✓
[6/6] Add session management... ✓
Checkpoint saved.

Phase 3: Tests & Validation
✅ Platform detected: Node.js / Next.js (pnpm)
Running: jest --findRelatedTests src/api/users.ts
✅ 14 passed, 0 failed
Lint: pnpm run lint ✅
Checkpoint saved.

Phase 4: Commit & PR
⚙️  Installing commit command...
✓ commit command installed successfully
Using enhanced commit workflow (/commit)...
✨ feat: implement user authentication system
Detected platform: GitHub
Creating PR via /checking-pr...

✓ Feature complete!
PR URL: https://github.com/user/repo/pull/42
```

### Example 4: Using Existing User Tools

```
> /feature-marker prd-payment-feature

Phase 0: Inputs Gate
✓ All inputs validated.

Phase 1: Analysis & Planning
✓ product-manager skill already installed (using user's version)
...

Phase 4: Commit & PR
✓ commit command already exists (using user's version)
...
```

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

feature-marker

Directory Structure

SKILL.md

Report

Notice