Aiwg workspace-health

Assess workspace alignment and recommend cleanup or realignment actions at key lifecycle transition points

install

source · Clone the upstream repo

git clone https://github.com/jmagly/aiwg

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/jmagly/aiwg "$T" && mkdir -p ~/.claude/skills && cp -r "$T/.agents/skills/workspace-health" ~/.claude/skills/jmagly-aiwg-workspace-health && rm -rf "$T"

manifest: .agents/skills/workspace-health/SKILL.md

source content

Workspace Health Check Skill

Assesses workspace alignment and suggests cleanup or realignment actions at key transition points.

Kernel Delegation

As of ADR-021,
workspace-health
delegates structural checks to the semantic memory kernel.

Delegation pattern:

```
workspace-health
```
retains its consumer-neutral health-check UX

Runs

memory-lint

for every installed framework in

.aiwg/frameworks/registry.json

Aggregates results across all consumers into a unified report
```
aiwg doctor
```
continues to call this skill unchanged

Backward compatibility: No UX changes. Output format unchanged.

@agentic/code/addons/semantic-memory/skills/memory-lint/SKILL.md

Triggers

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

"do I need to realign" → workspace realignment check
"is my workspace aligned" → alignment status check
"cleanup recommendations" → workspace prune suggestions

Auto-triggers:

After phase transition flow commands complete
After completing major features or intensive processes

Trigger Conditions Reference

This skill is commonly invoked:

At the end of phase transitions (flow commands)
After completing major features or intensive processes
When documentation appears out of sync
Manually via natural language phrases above

Assessment Checklist

1. Working Directory Health

checks:
  - name: working_directory_size
    description: Check if .aiwg/working/ has accumulated stale files
    threshold: ">10 files or >1MB"
    action: Suggest /workspace-prune-working

  - name: orphan_drafts
    description: Draft artifacts not linked to requirements
    action: Suggest review or archival

  - name: stale_locks
    description: Lock files older than 24h
    action: Suggest cleanup

2. Documentation Alignment

checks:
  - name: phase_documentation
    description: Current phase docs match project state
    sources:
      - .aiwg/planning/phase-plan-*.md
      - .aiwg/reports/*-completion-report.md
    action: Suggest /workspace-realign if mismatched

  - name: requirement_coverage
    description: All requirements have linked artifacts
    action: Suggest /check-traceability

  - name: architecture_drift
    description: Code diverged from documented architecture
    action: Suggest architecture review or ADR update

3. Artifact Freshness

checks:
  - name: stale_artifacts
    description: Key artifacts not updated in >30 days during active dev
    artifacts:
      - SAD (Software Architecture Document)
      - Risk Register
      - Test Strategy
    action: Flag for review

  - name: completion_markers
    description: Artifacts marked complete but phase still active
    action: Suggest status update

Output Format

## Workspace Health Report

**Overall Status**: [Healthy | Needs Attention | Requires Realignment]

### Quick Actions
- [ ] Run `/workspace-prune-working` - 15 stale files in working/
- [ ] Review 3 orphaned draft artifacts
- [ ] Update risk register (last modified 45 days ago)

### Detailed Findings

#### Working Directory
- Status: Needs cleanup
- Files: 15 (threshold: 10)
- Oldest: inception-notes-draft.md (created 2024-11-15)
- Recommendation: Promote or archive before next phase

#### Documentation Alignment
- Phase: Construction
- Last phase report: Elaboration completion (2024-12-01)
- Missing: Construction kickoff documentation
- Recommendation: Run `/flow-elaboration-to-construction` completion steps

#### Traceability
- Requirements covered: 85%
- Orphan code files: 3
- Recommendation: Run `/check-traceability` for details

Integration Points

Flow Command Endings

Add to flow command templates:

## Post-Completion

After this flow completes, consider running a workspace health check:

[workspace-health] Assessing workspace alignment...

If issues found, the skill will suggest appropriate cleanup commands.

Proactive Invocation

The orchestrator should invoke this skill:

When transitioning between SDLC phases
After completing iteration cycles
When user requests project status
Before major deployments

Implementation Notes

This skill should:

Read workspace state from
```
.aiwg/
```
structure
Compare against expected state for current phase
Generate actionable recommendations
NOT automatically execute cleanup (user confirms)

Related Commands

```
/workspace-prune-working
```
- Clean up working directory
```
/workspace-realign
```
- Reorganize documentation structure
```
/workspace-reset
```
- Full workspace reset (destructive)
```
/project-status
```
- Current project state
```
/check-traceability
```
- Verify requirement links

References

@$AIWG_ROOT/agentic/code/addons/aiwg-utils/README.md — aiwg-utils addon overview
@$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/human-authorization.md — Report findings and await user authorization before cleanup
@$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/vague-discretion.md — Concrete thresholds for health checks (file count, age)
@$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/README.md — SDLC phase structure that workspace health is measured against