# Projects

> Projects is an Agent Skill for productivity published in the me2resh/apexyard repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

List all managed projects with status, branch, open PRs, and open issue counts — portfolio-level view.

- Skill name: `projects`
- Category: [Productivity](https://www.openparable.com/skill/productivity/1)
- Source: https://github.com/me2resh/apexyard/blob/HEAD/.claude/skills/projects/SKILL.md
- Repository: me2resh/apexyard (479 GitHub stars when collected)

## SKILL.md

# /projects — List Managed Projects

Show every project ApexYard is managing, with a one-line health snapshot. Reads `apexyard.projects.yaml` at the root of the ops repo (your fork of apexyard) and iterates the registry.

## Path resolution

Read the registry path via `portfolio_registry`, the per-project docs dir via `portfolio_projects_dir`, and the ideas backlog via `portfolio_ideas_backlog` — all from `.claude/hooks/_lib-portfolio-paths.sh`. Source the helper at the top of any bash block that touches those paths:

```bash
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-read-config.sh"
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-portfolio-paths.sh"
registry=$(portfolio_registry)
```

Defaults match today's single-fork layout (`./apexyard.projects.yaml`, `./projects`, `./projects/ideas-backlog.md`). Adopters in split-portfolio mode override the `portfolio.{registry, projects_dir, ideas_backlog}` keys in `.claude/project-config.json`. Don't hardcode literal `apexyard.projects.yaml` or `projects/` paths in bash blocks — the helper resolves whichever mode the adopter is in. See `docs/multi-project.md`.

## Usage

```
/projects
/projects --status active
/projects --json
```

## Behaviour

Read `apexyard.projects.yaml`:

```yaml
version: 1
projects:
  - name: example-app
    repo: your-org/example-app
    workspace: workspace/example-app
    docs: projects/example-app
    status: active
    roles: [tech-lead, backend-engineer]
```

For each project, gather:

```bash
# If a local workspace clone exists, use it for git data
if [ -d "{workspace}" ]; then
  BRANCH=$(git -C {workspace} rev-parse --abbrev-ref HEAD)
  LAST=$(git -C {workspace} log -1 --format='%h %ar %s')
  DIRTY=$(git -C {workspace} status --porcelain | wc -l | tr -d ' ')
else
  BRANCH="(not cloned)"
  LAST="-"
  DIRTY="-"
fi

# Always go to GitHub for PRs / issues (project of record)
PRS=$(gh -R {repo} pr list --state open --json number --jq 'length')
ISSUES=$(gh -R {repo} issue list --state open --json number --jq 'length')
```

If `apexyard.projects.yaml` doesn't exist at the ops-repo root, print a clear error pointing the user at `apexyard.projects.yaml.example` and `docs/multi-project.md` for the setup guide.

## Output format

A markdown table:

```markdown
| Project | Status | Branch | PRs | Issues | Last Commit | Dirty |
|---------|--------|--------|-----|--------|-------------|-------|
| example-app | active | main | 3 | 12 | 2h ago — fix(...) | 0 |
| billing-api | handover | feature/GH-4 | 1 | 8 | 1d ago — feat(...) | 2 |
| marketing-site | paused | main | 0 | 1 | 30d ago — chore(...) | 0 |
```

After the table, a summary line:

```
3 projects · 4 open PRs · 21 open issues · 1 dirty workspace
```

And, if relevant, flag rows that need attention:

```
⚠ marketing-site: last commit 30 days ago (paused or stale?)
⚠ billing-api: 2 uncommitted files in workspace
```

## Filters

| Flag | Effect |
|------|--------|
| `--status active` | Only show projects with `status: active` |
| `--status handover` | Only show projects mid-handover |
| `--status paused` | Only show paused projects |
| `--status archived` | Only show archived projects |
| `--json` | Emit machine-readable JSON instead of a table |

## Errors and edge cases

| Condition | Behaviour |
|-----------|-----------|
| No `apexyard.projects.yaml` at the ops-repo root | Print a clear error and a sample registry to copy |
| Project listed but workspace path missing | Show row with `(not cloned)` — don't fail |
| `gh` not authenticated | Show row with `?` for PRs/issues — don't fail |
| `repo` field looks invalid | Skip with a warning, continue with the rest |

## Rules

1. **Registry-driven** — the registry is the source of truth; no discovery fallback
2. **Source of truth for PRs/issues = GitHub** — never read from a stale local file
3. **Source of truth for branch state = local workspace** — `gh` doesn't know about your dirty files
4. **Don't silently fail on a missing project** — show the row, mark the gap
5. **Sort by status then name** — active first, then handover, then paused, then archived
6. **Never modify the registry from this skill** — read-only

## Related skills

- `/inbox` — same registry, but filtered to "needs your attention"
- `/status` — per-project deep dive (current branch, recent commits)
- `/tasks` — actionable list with URLs
- `/handover` — onboard a new repo into the registry

---

*Part of [ApexYard](https://github.com/me2resh/apexyard) — multi-project SDLC framework for Claude Code · MIT.*

---

Source: https://www.openparable.com/skill/productivity/projects (OpenParable). Cite the canonical URL above.
