# Project State Reader

> 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.

- **Type:** Skill
- **Install:** `agentstack add skill-camoa-claude-skills-project-state-reader`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [camoa](https://agentstack.voostack.com/s/camoa)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [camoa](https://github.com/camoa)
- **Source:** https://github.com/camoa/claude-skills/tree/main/ai-dev-assistant/skills/project-state-reader

## Install

```sh
agentstack add skill-camoa-claude-skills-project-state-reader
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 fallback
- `codePath` — absolute path (string) if declared and resolves, or `null` if docs-only / unknown
- `folder` — the absolute path passed in
- `playbookSets` — *(v1.1+)* array of dev-guides path slugs the project subscribes to (e.g., `["/best-practices/"]`). 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-playbook`
- `userPlaybookState` — *(v1.1+)* `"unset"` \| `"docs-only-no-playbook"` \| `"set"`
- `playbookResolutions` — *(v1.1+)* array of `{topic, set}` entries recording per-topic multi-set contradiction resolutions
- `worktreeByDefault` — *(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+)

```markdown
**Playbook Sets:** /best-practices/, /best-practices/
**User Playbook:** /home/me/projects/idexx/docs/playbook.md
**User Playbook State:** set

**Playbook Resolutions:**
- font-sizing → /best-practices/
- bem-methodology → /best-practices/
```

| Line | Semantics |
|---|---|
| `**Playbook Sets:** ` | 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:** ` | 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

```bash
"${CLAUDE_PLUGIN_ROOT}/scripts/project-state-read.sh" "/abs/path/to/project/folder"
```

Parse with `jq`. Example:

```bash
OUTPUT=$("${CLAUDE_PLUGIN_ROOT}/scripts/project-state-read.sh" "$PROJECT_DIR")
CODE_PATH=$(jq -r '.codePath // empty'  0' /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 check
- `analysis-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 script
- `task-frontmatter-reader` skill (v2.0.0) — same design pattern, task-level metadata instead of project-level

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [camoa](https://github.com/camoa)
- **Source:** [camoa/claude-skills](https://github.com/camoa/claude-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-camoa-claude-skills-project-state-reader
- Seller: https://agentstack.voostack.com/s/camoa
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.