Free SKILL.md scraped from GitHub. Clone the repo or copy the file directly into your Claude Code skills directory.
npx versuz@latest install jmagly-aiwg-agentic-code-addons-aiwg-utils-skills-project-statusgit clone https://github.com/jmagly/aiwg.gitcp aiwg/SKILL.MD ~/.claude/skills/jmagly-aiwg-agentic-code-addons-aiwg-utils-skills-project-status/SKILL.md---
namespace: aiwg
name: project-status
platforms: [all]
description: Cross-framework project status aggregator — discovers contributors from installed frameworks, runs declarative detection, produces a unified status report.
commandHint:
argumentHint: "[project-directory=.] [--json] [--guidance \"text\"]"
allowedTools: Read, Glob, Grep, Bash
model: sonnet
category: aiwg-utility
---
<!-- AIWG-SKILL-CALLOUT -->
> **Skill access pattern (post-kernel-pivot, 2026.5+)**
>
> Skill names referenced in this document are AIWG skills, **not slash commands**. Most are not kernel-listed and cannot be invoked as `/skill-name` by the platform. Reach them via:
>
> ```bash
> aiwg discover "<capability>"
> aiwg show skill <name>
> ```
>
> Only kernel-listed skills (`aiwg-doctor`, `aiwg-refresh`, `aiwg-status`, `aiwg-help`, `use`, `steward`) are directly invokable as slash commands. See [skill-discovery rule](../../../addons/aiwg-utils/rules/skill-discovery.md).
# Project Status (Cross-Framework Aggregator)
## Task
Produce a unified status report covering every installed framework, addon, or
extension that ships a `kind: status` contributor and is in active use on this
project.
This is the cross-framework aggregator described in ADR-023 §Reference
contributor frontmatter. It replaces the prior SDLC-only project-status
behavior. SDLC-specific reporting now lives in the SDLC framework's status
contributor at `agentic/code/frameworks/sdlc-complete/status/contributor.md` —
when SDLC is the only contributor in use, the resulting report is functionally
equivalent to the prior behavior.
## Parameters
- **`[project-directory]`** (optional): Path to project root. Default: current directory `.`
- **`--json`** (optional): Emit machine-readable JSON instead of human-readable markdown
- **`--guidance "text"`** (optional): Extra context the agent should weigh while interpreting contributor blocks
## Workflow
### Step 1: Locate the registry and project root
Read `.aiwg/frameworks/registry.json` from the project root. The registry lists
installed frameworks/addons/extensions by `id`. If the file is missing, treat
it as zero installed frameworks — discovery still finds project-local
contributors.
```bash
cat ./.aiwg/frameworks/registry.json 2>/dev/null
```
### Step 2: Discover candidate contributors
Two sources, processed in order:
1. **Framework-shipped contributors** — for each `id` in the registry, look up
its source path under the AIWG installation. Try in order:
- `<AIWG_ROOT>/agentic/code/frameworks/<id>/status/contributor.md`
- `<AIWG_ROOT>/agentic/code/addons/<id>/status/contributor.md`
- `<AIWG_ROOT>/agentic/code/extensions/<id>/status/contributor.md`
Use `Glob` to discover, then `Read` to load the contributor file.
2. **Project-local contributors** — every `*.md` file in
`<project-root>/.aiwg/contributors/status/`. These are user-authored
contributors that do not require forking a framework.
### Step 3: Validate and run detection
For each candidate file:
1. Parse YAML frontmatter. Skip with a warning if frontmatter is malformed
or missing required fields (`kind`, `domain`, `description`, `detect.glob`).
The schema is published at
`<AIWG_ROOT>/agentic/code/addons/aiwg-utils/skills/project-status/contributor.schema.json`
— `aiwg validate-metadata` enforces it at deploy time, so most files
reaching this step are valid.
2. Run the contributor's `detect.glob` patterns against the project root using
`Glob`. Deduplicate matches. If unique match count is less than
`detect.minCount` (default 1), the contributor is **installed but not in
use** — silently filter out.
3. For surviving contributors, the agent reads the contributor file's body
to learn what to report and how to format it.
### Step 4: Gather state per contributor
For each in-use contributor, follow its body's guidance to read source files
and compute reported state. Contributors are descriptive — they tell the
agent what to look at; they do not run code.
Keep blocks compact. Per ADR-023 §Output voice, contributors emit observed
state (counts, dates, phase names). Do **not** synthesize prescriptive
"recommended commands" inside a contributor's block.
### Step 5: Render the unified report
Default (markdown) output shape:
```
Project: <project-name> (<detected-domain-summary>)
├─ <Domain 1>: <one-line summary> (origin: <framework-id>)
│ ├─ <fact 1>
│ ├─ <fact 2>
│ └─ <fact N>
├─ <Domain 2>: <one-line summary> (origin: <framework-id>)
│ └─ ...
└─ <Domain K>: <one-line summary> (origin: project-local)
└─ ...
```
Every block carries an **`origin:`** stamp — the framework id (e.g.
`sdlc-complete`, `media-curator`) or the literal `project-local`. This lets
the user see at a glance whether a finding came from a framework's
contributor or a project-specific override.
### Step 6: Handle empty discovery
If discovery returns zero in-use contributors:
- **In a project that has frameworks installed but none are in use yet**:
surface "No active framework contributors detected. Run
`intake-wizard` if this is a new project, or check
`.aiwg/frameworks/registry.json` to confirm what's installed."
- **In a project with no `.aiwg/`**: defer to the heuristic fallback
described in `<AIWG_ROOT>/agentic/code/addons/aiwg-utils/skills/project-status/heuristic-fallback.md`
(added by issue #941). When that file is not yet present, surface a
short "No project state detected" message.
## --json output
Returns a structured array of contributor blocks. Stable shape:
```json
{
"project_root": "/abs/path",
"contributors": [
{
"origin": "sdlc-complete",
"domain": "SDLC",
"summary": "Construction phase, iteration 12, 3 open risks",
"detail": [
{ "label": "Phase", "value": "Construction (entered 2026-04-01)" },
{ "label": "Iteration", "value": "12 of 18 planned" }
]
}
],
"skipped": [
{ "origin": "media-curator", "reason": "detection-no-match" }
]
}
```
Downstream tooling (CI status badges, dashboards) consumes this shape directly.
## Failure mode
Per ADR-023 §Failure mode:
- A contributor that fails frontmatter parsing or validation is **skipped**
with reason `schema-violation`; aggregation continues.
- A contributor whose detection throws (rare — only filesystem permission
errors should cause this) is skipped with reason `detection-error`.
- One bad contributor never aborts the whole report.
When `--json` is set, skips appear under the `skipped` array. In markdown
output, skips are summarized under a `─ Skipped contributors` footer when
non-empty.
## Anti-Patterns
- **Do not invent contributor state.** If a contributor's detection matches
but its source files are absent or unreadable, emit the block with a
clear "details unavailable" note rather than fabricating values.
- **Do not merge or reorder contributor blocks.** Registry order and
project-local-last is the contract per ADR-023 §Discovery Algorithm.
Users rely on it for predictable diffs over time.
- **Do not call into other AIWG commands** (`aiwg index build`, `aiwg run …`)
from this skill. Status reporting is read-only. If a contributor needs
built indexes, surface their absence rather than building them mid-report.
## References
- @.aiwg/architecture/decisions/ADR-023-contributor-discovery-convention.md — Convention this skill implements
- @$AIWG_ROOT/agentic/code/addons/aiwg-utils/skills/project-status/contributor.schema.json — Published JSON Schema for `kind: status` frontmatter
- @$AIWG_ROOT/src/contributors/discover.ts — TS reference implementation used by `aiwg validate-metadata`; demonstrates the discovery algorithm in code
- @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/status/contributor.md — Reference status contributor (SDLC framework)
- @$AIWG_ROOT/agentic/code/frameworks/media-curator/status/contributor.md — Reference status contributor (media archives)
- @$AIWG_ROOT/agentic/code/frameworks/research-complete/status/contributor.md — Reference status contributor (research corpora)
- @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/skills/project-health-check/SKILL.md — Complementary skill: code and team health metrics (out of scope for project-status)