project-awareness
Comprehensive project context detection and state awareness. Use when relevant to the task.
When & Why to Use This Skill
The project-awareness skill is a foundational context-provider designed to give Claude a comprehensive understanding of a software project's state. By automatically detecting the technology stack, development phase, team configuration, and recent Git activity, it ensures that the AI agent operates with full situational awareness. This skill minimizes manual context-setting, reduces errors in task execution, and provides proactive recommendations based on the project's current lifecycle stage.
Use Cases
- 1. Automated Project Onboarding: Instantly identify the tech stack (e.g., React, Node.js, Python) and repository structure when starting a new session to provide immediate, relevant assistance.
- 2. Lifecycle & Phase Tracking: Determine the current development stage (Inception, Elaboration, Construction, etc.) and check if specific 'gate' criteria are met before moving to the next phase.
- 3. Team & Role Coordination: Quickly identify which team members or specialized agents are assigned to specific tasks or architectural components by parsing configuration files.
- 4. Progress Reporting & Blocker Detection: Analyze recent commits and artifact changes to generate status reports, identify what's blocking the team, and suggest the most logical next steps.
| name | project-awareness |
|---|---|
| description | Comprehensive project context detection and state awareness. Use when relevant to the task. |
project-awareness
Comprehensive project context detection and state awareness.
Triggers
- "what project is this"
- "project context"
- "what phase are we in"
- "where are we?"
- "what's next?"
- "project status"
- "current phase"
- "who is on the team"
- "what framework is active"
- "ready to transition?"
- "what's blocking us?"
- (Auto-triggered at session start for context building)
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:
Detects project type:
- Monorepo vs single project
- Library vs application vs service
- Web, API, CLI, mobile, etc.
- Programming languages and frameworks
Identifies AIWG state:
- Installed frameworks (SDLC, MMK, addons)
- Current lifecycle phase
- Active iteration (if applicable)
- Deployed agents and commands
Parses team configuration:
- Team roster from
.aiwg/team/ - Agent assignments
- Role responsibilities
- Team roster from
Loads recent activity:
- Git log (recent commits, active branches)
- Recent artifact changes
- Open PRs and issues
Builds context object:
- Structured data for other skills
- Summary for user display
- Recommendations for next actions
Trigger Phrase Mappings
| Natural Language | Action |
|---|---|
| "Where are we?" | Check phase status, recent activity |
| "What's next?" | Identify pending tasks, next milestone |
| "Project status" | Full status report |
| "Current phase" | Phase name + completion percentage |
| "Ready to transition?" | Gate criteria check |
| "What's blocking us?" | Risk register + blockers |
| "How long until..." | Milestone progress estimate |
| "Who owns..." | Team and agent assignments |
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
| Indicator | Project Type |
|---|---|
| package.json + src/index.ts | Node.js application |
| package.json + lib/ | Node.js library |
| setup.py or pyproject.toml | Python package |
| Cargo.toml | Rust project |
| go.mod | Go module |
| pom.xml | Java Maven project |
| turbo.json or lerna.json | Monorepo |
Framework Stack Detection
| Files | Framework |
|---|---|
| next.config.js | Next.js |
| angular.json | Angular |
| vite.config.ts | Vite |
| django, manage.py | Django |
| express in package.json | Express |
| fastapi in requirements | FastAPI |
AIWG State Detection
| Location | Information |
|---|---|
| .aiwg/ | AIWG artifacts directory exists |
| .aiwg/config/registry.json | Installed frameworks |
| .aiwg/planning/phase-plan-*.md | Current phase |
| .aiwg/planning/iteration-*.md | Current iteration |
| .claude/agents/ | Deployed agents |
| .claude/commands/ | Deployed commands |
Phase Detection Heuristics
| Artifacts Present | Likely Phase |
|---|---|
| intake/ only | Concept/Inception |
| requirements/ + architecture/ draft | Inception |
| architecture/ baselined | Elaboration |
| testing/ + deployment/ draft | Construction |
| deployment/ baselined | Transition |
| All baselined + production logs | Production |
Phase Reference
| Phase | Description | Key Artifacts |
|---|---|---|
| Inception | Vision, risks, feasibility | intake forms, business case |
| Elaboration | Architecture baseline | SAD, ADRs, test strategy |
| Construction | Feature implementation | code, tests, reviews |
| Transition | Deployment, handover | runbooks, training |
| Production | Operations, iteration | monitoring, incidents |
Command Bindings
This skill may trigger these commands based on context:
| Context | Command |
|---|---|
| User wants full report | /project-status |
| User asks about health | /project-health-check |
| User asks about gate readiness | /flow-gate-check [phase] |
| User seems lost on next steps | Suggest relevant flow command |
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 selectiongate-evaluation: Knows what gate to checkparallel-dispatch: Knows which agents are relevanttemplate-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