Implementation

Invoke the alignment-analyzer agent to find conflicts between PROJECT.md and reality, then guide interactive fixing.

Align Project

GenAI-powered project alignment analysis and interactive fixing

Usage

/align-project

Time: 5-20 minutes (depending on issues found) Interactive: Agent asks about each conflict found GenAI-Powered: Uses alignment-analyzer agent for intelligent analysis

How It Works

The alignment-analyzer agent works with you to align your project:

Phase 1: Analysis (GenAI Agent)

The agent:

✅ Reads PROJECT.md (source of truth)
✅ Scans your codebase for actual implementation
✅ Checks documentation against reality
✅ Identifies conflicts and misalignments
✅ Explains each issue in context

Phase 2: Interactive Fixing (GenAI + You)

For each conflict found, the agent asks:

PROJECT.md says: "REST API only, no GraphQL"
Reality shows: graphql/ directory with resolvers
Status: GraphQL implementation exists

What should we do?
A) YES - PROJECT.md is correct (remove GraphQL)
B) NO - Update PROJECT.md to include GraphQL

Your choice [A/B]:

The agent intelligently:

Asks binary questions (no ambiguity)
Explains impact of each choice
Groups related conflicts
Suggests fixes based on your answers

Phase 3: Execution

After all questions answered, the agent:

✅ Updates PROJECT.md (if needed)
✅ Suggests code changes (if needed)
✅ Creates documentation (if needed)
✅ Removes scope drift (if needed)
✅ Commits changes

Example: Analyzing Misalignment

🔍 Analyzing project alignment with PROJECT.md...

Found 5 conflicts:

CONFLICT #1: GraphQL Scope Mismatch
────────────────────────────────────
PROJECT.md says:
  SCOPE (Out of Scope):
    - GraphQL API

Reality shows:
  graphql/ directory exists with resolvers implemented

What should we do?
A) YES - PROJECT.md is correct (remove GraphQL code)
B) NO - Update PROJECT.md to include GraphQL

Your choice [A/B]: A

Action: Remove graphql/ directory and update PROJECT.md
Impact: Removes ~200 lines of code (not in scope)

Example: Completing a Conflict

CONFLICT #2: Missing Test Structure
────────────────────────────────────
PROJECT.md says:
  Tests organized in: tests/unit/, tests/integration/

Reality shows:
  Only tests/ directory exists (no subdirectories)

What should we do?
A) YES - PROJECT.md is correct (organize tests)
B) NO - Update PROJECT.md to reflect current structure

Your choice [A/B]: A

Action: Organize existing tests into unit/integration/uat
Impact: Makes testing structure match documentation

Typical Workflow

First Time Setup

# 1. Run alignment
/align-project

# 2. Agent analyzes and asks about each conflict
# 3. You choose A (PROJECT.md correct) or B (update PROJECT.md)
# 4. Agent implements your choices
# 5. Agent commits changes with summary

Periodic Checks

# Check alignment
/align-project

# If fully aligned:
# ✅ No conflicts found - project is well-aligned!

# If conflicts found:
# Answer each question to resolve

What the Agent Does

Analysis Phase

✅ Reads PROJECT.md entirely
✅ Scans codebase (src/, lib/, components/, etc.)
✅ Checks documentation (README, docs/, etc.)
✅ Identifies conflicts between stated goals and reality
✅ Groups related issues together

Question Phase

✅ Asks binary questions (clear A or B choices)
✅ Explains context for each conflict
✅ Shows what code exists vs. what PROJECT.md says
✅ Suggests practical fixes

Execution Phase

✅ Updates PROJECT.md (if you choose B)
✅ Removes unscoped code (if you choose A)
✅ Organizes files to match scope
✅ Commits changes with clear messages

Safety Features

✅ Analysis before action: Agent shows conflicts before making changes ✅ Binary questions: No ambiguity - clear choices ✅ Clear impact: Agent explains what each choice does ✅ Reversible: Changes are committed (easy rollback) ✅ Stop anytime: Can exit at any point

When to Use This Command

Run /align-project when:

🆕 First time setup (understand project scope)
📊 After major development (ensure docs match code)
🔄 After PROJECT.md changes (verify implementation updated)
🔍 Before releases (ensure scope is accurate)
👥 Onboarding team members (clarify what's in/out of scope)

No need if:

Project already aligned (agent will say "no conflicts found")
You just want to code quickly (can skip)

Troubleshooting

"PROJECT.md not found"

# Create PROJECT.md first
/setup

# Then run alignment
/align-project

"Agent can't find files"

Check that PROJECT.md exists and is readable
Verify codebase has typical structure (src/, lib/, etc.)
Agent may need broader scope to find features

"Disagreeing with agent's analysis"

Agent analyzes based on PROJECT.md being the source of truth. If you disagree:

Choose B) NO to update PROJECT.md instead
Agent will adapt the documentation to match reality

Related Commands

/setup - Create or update PROJECT.md
/test - Run tests after alignment
/auto-implement - Autonomous feature development

Use this to find conflicts between your documented goals and actual implementation. Agent intelligently guides you to alignment.