From ai-dev-assistant
Reads project_state.md to produce structured JSON metadata (codePath, playbookSets, userPlaybook, project_name) with defensive error handling. Useful for framework commands needing project-level context without blocking on malformed input.
How this skill is triggered — by the user, by Claude, or both
Slash command
/ai-dev-assistant:project-state-readerinheritThis skill is limited to the following tools:
These tools are removed from Claude's available pool while this skill is active:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Thin wrapper around `${CLAUDE_PLUGIN_ROOT}/scripts/project-state-read.sh`. The script parses the project's `project_state.md` header block and emits structured JSON. This skill exists to give it a Skill-tool-callable name and to document the contract.
Thin wrapper around ${CLAUDE_PLUGIN_ROOT}/scripts/project-state-read.sh. The script parses the project's project_state.md header block and emits structured JSON. This skill exists to give it a Skill-tool-callable name and to document the contract.
Input: one argument — absolute path to a project folder (the one containing project_state.md).
Output: single JSON object to stdout. Exit code always 0.
Fields:
project_name — from the H1 line in project_state.md, or folder basename fallbackcodePath — absolute path (string) if declared and resolves, or null if docs-only / unknownfolder — the absolute path passed inplaybookSets — (v1.1+) array of dev-guides path slugs the project subscribes to (e.g., ["<framework>/best-practices/<author>"]). Falls back to the plugin's defaults.json playbookSets when field absent. Empty array when explicit none.playbookSetsSource — (v1.1+) "explicit" (field present with values) | "explicit-none" (field is literal none) | "default" (field absent, defaults applied)userPlaybook — (v1.1+) absolute path to project-local playbook file, or null when state is unset or docs-only-no-playbookuserPlaybookState — (v1.1+) "unset" | "docs-only-no-playbook" | "set"playbookResolutions — (v1.1+) array of {topic, set} entries recording per-topic multi-set contradiction resolutionsworktreeByDefault — (v1.2+) boolean. When true, /implement always recommends a worktree. Defaults to false when field absent.warnings — array of {code, detail} entries| Input state | Warning code |
|---|---|
| Project folder does not exist | folder_missing |
Folder exists, project_state.md missing | project_state_md_missing |
project_state.md has no **Code path:** line | code_path_unknown |
**Code path:** /some/dir but that directory doesn't exist | code_path_missing |
Declared (docs-only) sentinel | (none — legitimate docs-only state, codePath is null) |
project_state.mdAccepted on the one-line **Code path:** metadata entry:
**Code path:** /absolute/path — non-null string; path normalized via realpath -m**Code path:** (docs-only) — null; explicit docs-only declarationCase-insensitive match on the label.
project_state.md (v1.1+)**Playbook Sets:** <framework>/best-practices/<author1>, <framework>/best-practices/<author2>
**User Playbook:** /home/me/projects/idexx/docs/playbook.md
**User Playbook State:** set
**Playbook Resolutions:**
- font-sizing → <framework>/best-practices/<author1>
- bem-methodology → <framework>/best-practices/<author2>
| Line | Semantics |
|---|---|
**Playbook Sets:** <ids,...> | Comma-separated set IDs |
**Playbook Sets:** none | Explicit opt-out — empty list, source explicit-none |
| (line absent) | Use the plugin's defaults.json playbookSets; source default |
**User Playbook:** <abs path> | Project-local playbook file |
**User Playbook State:** unset | docs-only-no-playbook | set | 3-state field; mirrors Code Path State precedent |
**Playbook Resolutions:** (multi-line list) | Per-topic multi-set choices |
"${CLAUDE_PLUGIN_ROOT}/scripts/project-state-read.sh" "/abs/path/to/project/folder"
Parse with jq. Example:
OUTPUT=$("${CLAUDE_PLUGIN_ROOT}/scripts/project-state-read.sh" "$PROJECT_DIR")
CODE_PATH=$(jq -r '.codePath // empty' <<<"$OUTPUT")
UNKNOWN=$(jq -e '[.warnings[] | select(.code == "code_path_unknown")] | length > 0' <<<"$OUTPUT" >/dev/null && echo true || echo false)
/ai-dev-assistant:set-code-path — read current value to show in confirm prompt/ai-dev-assistant:propose-epics — get codePath before invoking analysis agent/ai-dev-assistant:research — pre-analysis hook needs codePath for strong-signal checkanalysis-agent — inputs codePath (resolved by caller; agent doesn't call this skill directly)Future consumers that need project-level metadata should call this skill rather than parsing project_state.md directly.
project_state.md from this skill. Reading only. Writes go through /set-code-path command or the /new creation flow.warnings[] as a blocking error — warnings are observations.${CLAUDE_PLUGIN_ROOT}/scripts/project-state-read.sh — the scripttask-frontmatter-reader skill (v2.0.0) — same design pattern, task-level metadata instead of project-levelnpx claudepluginhub camoa/claude-skills --plugin ai-dev-assistantParses a task's alignment.md scope contract (Goal, Expected result, Success criteria, Non-goals) into structured JSON with defensive error handling and warnings.
Displays project status, roadmap progress, blockers, and next-action suggestions based on workflow state. Use for progress checks and orientation.
Displays Plan-Build-Run project status dashboard, progress, blockers from .planning files, and suggests next actions.