| name | project-state-reader |
| description | Use when a framework command needs project-level metadata (codePath, playbookSets, userPlaybook, playbookResolutions, project_name). Reads project_state.md defensively via scripts/project-state-read.sh and returns structured JSON with warnings. Never blocks on malformed input. |
| version | 1.3.0 |
| user-invocable | false |
| model | inherit |
| allowed-tools | Bash |
| disallowed-tools | Write, Edit |
Project State Reader
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.
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
Defensive posture (never throws)
| 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) |
Code path sentinels in project_state.md
Accepted 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 declaration- (line absent) — null; first-use prompt should fire
Case-insensitive match on the label.
Playbook fields in 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 |
Invocation
"${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)
Consumers (v3.11.0+)
/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.
Do NOT
- Do not write to
project_state.md from this skill. Reading only. Writes go through /set-code-path command or the /new creation flow.
- Do not treat non-empty
warnings[] as a blocking error — warnings are observations.
- Do not duplicate the parsing logic elsewhere. Call this skill or the script.
See also
${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-level
