project-awareness

project-awareness

Comprehensive project context detection and state awareness.

Triggers

Alternate expressions and non-obvious activations (primary phrases are matched automatically from the skill description):

• "where are we" / "what's next" → project state summary
• "what's blocking" in project context → status + blockers
• "sprint status" → iteration awareness

Purpose

This skill provides rich project context awareness including:

• Project type and technology stack detection
• AIWG framework state (installed frameworks, current phase)
• Team configuration and agent assignments
• Recent activity and artifact status
• Active work detection (branches, PRs, iterations)
• Recommendations for next actions

Behavior

When triggered, this skill:

1. Detects project type:

   • Monorepo vs single project
   • Library vs application vs service
   • Web, API, CLI, mobile, etc.
   • Programming languages and frameworks

2. Identifies AIWG state:

   • Installed frameworks (SDLC, MMK, addons)
   • Current lifecycle phase
   • Active iteration (if applicable)
   • Deployed agents and commands

3. Parses team configuration:

   • Team roster from .aiwg/team/
   • Agent assignments
   • Role responsibilities

4. Loads recent activity:

   • Git log (recent commits, active branches)
   • Recent artifact changes
   • Open PRs and issues

5. Builds context object:

   • Structured data for other skills
   • Summary for user display
   • Recommendations for next actions

Trigger Phrase Mappings

Information Sources

Primary Sources (Check First)

• .aiwg/planning/phase-status.md - Current phase and progress
• .aiwg/planning/iteration-plan.md - Current iteration tasks
• .aiwg/gates/ - Gate criteria and validation status

Secondary Sources

• .aiwg/risks/risk-register.md - Active risks and blockers
• .aiwg/team/agent-assignments.md - Who's working on what
• .aiwg/requirements/ - Requirements completion status
• .aiwg/architecture/ - Architecture baseline status

Context Sources

• CLAUDE.md - Project configuration
• .aiwg/intake/project-intake.md - Original project scope
• Git log - Recent activity

Context Object Structure

{
  "project": {
    "name": "my-project",
    "type": "application",
    "subtype": "web-api",
    "root": "/path/to/project",
    "description": "From package.json or README"
  },

  "tech_stack": {
    "languages": ["typescript", "python"],
    "runtime": "node",
    "framework": "express",
    "package_manager": "npm",
    "database": "postgresql",
    "testing": "vitest",
    "ci_cd": "github-actions"
  },

  "aiwg": {
    "installed": true,
    "frameworks": ["sdlc-complete"],
    "addons": ["aiwg-utils", "voice-framework"],
    "phase": "elaboration",
    "iteration": 3,
    "agents_deployed": 45,
    "commands_deployed": 38
  },

  "team": {
    "members": [
      {"name": "John", "role": "tech-lead", "agent": "architecture-designer"}
    ],
    "agent_assignments": {
      "architecture-designer": "John",
      "test-architect": "Jane"
    }
  },

  "activity": {
    "current_branch": "feature/user-auth",
    "recent_commits": [...],
    "open_prs": [...],
    "modified_artifacts": [...],
    "last_gate_check": "2025-12-05"
  },

  "artifacts": {
    "total": 24,
    "by_status": {
      "draft": 5,
      "review": 3,
      "baselined": 16
    },
    "recent": [...]
  },

  "recommendations": [
    "Complete SAD review (2 reviewers pending)",
    "Run gate-check for Elaboration exit",
    "Update risk register (7 days stale)"
  ]
}

Response Formats

Quick Status (Default)

Phase: [Current Phase] ([X]% complete)
Iteration: [N] of [Total]
Next Milestone: [Milestone Name] - [Date/Status]
Blockers: [Count] ([List if < 3])

Full Status (On Request)

## Project: [Name]
Phase: [Phase] | Iteration: [N]
Started: [Date] | Target: [Date]

### Completion
- Requirements: [X]%
- Architecture: [X]%
- Implementation: [X]%
- Testing: [X]%

### Active Work
- [Task 1] - [Owner] - [Status]
- [Task 2] - [Owner] - [Status]

### Blockers/Risks
- [Risk 1] - [Severity] - [Mitigation]

### Next Steps
1. [Action 1]
2. [Action 2]

Detection Methods

Project Type Detection

Framework Stack Detection

AIWG State Detection

Phase Detection Heuristics

Phase Reference

Command Bindings

This skill may trigger these commands based on context:

Usage Examples

Session Start Context

Model auto-invokes project-awareness

Returns:
"Project: MyAPI (Node.js/Express API)
Phase: Elaboration (Iteration 3)
Team: 4 members assigned
Recent: SAD approved, Test Plan in review

Recommendations:
- Complete Test Plan review
- Begin Construction planning"

Explicit Query

User: "What phase are we in?"

Skill returns:
"Current Phase: Elaboration
Milestone: Architecture Baseline (ABM)
Progress: 75% complete

Completed:
✓ Requirements baseline
✓ SAD approved
✓ 3/5 ADRs written

Remaining:
- Test Plan approval
- Risk register update
- Gate check"

Team Query

User: "Who owns the architecture?"

Skill returns:
"Architecture ownership:
- Lead: John (architecture-designer)
- Reviewers: Jane (security-architect), Bob (test-architect)

Recent activity:
- SAD v1.2 updated 2 days ago
- ADR-005 created yesterday"

CLI Usage

# Full context dump
python project_awareness.py --full

# Specific aspects
python project_awareness.py --tech-stack
python project_awareness.py --aiwg-state
python project_awareness.py --team
python project_awareness.py --activity

# JSON output
python project_awareness.py --full --json

# Recommendations only
python project_awareness.py --recommendations

Integration

This skill provides context for:

• artifact-orchestration: Knows current phase for artifact selection
• gate-evaluation: Knows what gate to check
• parallel-dispatch: Knows which agents are relevant
• template-engine: Knows project name, type for templates
• All SDLC flows: Phase and iteration context
• All other skills that need project context

Caching

Context is cached for performance:

• Tech stack: Cached until package files change
• AIWG state: Cached for 5 minutes
• Activity: Refreshed on each call
• Team: Cached until team files change

Cache location: .aiwg/working/context-cache.json

References

• Team configuration: .aiwg/team/
• Phase plans: .aiwg/planning/
• Registry: .aiwg/config/registry.json
• Artifact index: .aiwg/reports/artifact-index.json