Skill: adelvillar1/project-methodology (version 1.0.1)

--- name: project-methodology description: >- Complete project lifecycle methodology for Hermes Agent sessions. A single, integrated workflow covering warmup → plan → build → recap → wrapup — with context loading, feature planning, recap drafting, handoff verification, and project scaffolding. Every session follows the same cycle; nothing falls through the cracks. version: 1.0.0 author: Alejandro Del Villar license: MIT metadata: hermes: homepage: https://github.com/adelvillar1 tags: [project-management, methodology, session-lifecycle, warmup, planning, recaps, wrapup, context-loading, continuity] related_skills: [project-knowledge-graph, codebase-survey, slim-claude-md, tech-stack-evaluation, init-project-structure] triggers: - "warmup" - "where did we leave off" - "what.*open" - "continue from yesterday" - "pick up where we left off" - "plan.*feature" - "draft.*plan" - "write.*recap" - "wrap up" - "we.*done" - "sign off" - "close out" - "init.*project" - "scaffold.*project" security: scope: persistence: - "Reads project memory files (e.g. .md), docs/recaps/*.md, docs/plans/*.md, docs/architecture/*.md, docs/features/*.md, TECHNICAL-DOCUMENTATION.md, FUNCTIONAL-SPECIFICATIONS.md" - "Reads git log and git status to verify post-recap work" - "Writes recap files to docs/recaps/ and plan files to docs/plans/" - "Modifies project memory file 'Today's state' section when stale" - "Modifies plan file frontmatter (status, updated date) on completion" safety: - "Never auto-commits — all file writes are explicitly reviewed by the user" - "Local env file (CLAUDE.local.md) requires explicit user approval before reading" - "Direct database or API queries require explicit user approval in the current turn" - "Plan files are markdown with frontmatter — no executable code" - "Recap content is human-readable session journaling, not automated data collection" --- # Project Methodology > A complete, battle-tested session lifecycle for Hermes Agent. Every session > follows the same cycle: warm up → plan → build → recap → wrap up. This skill > integrates all five stages into one workflow so nothing is forgotten and > every session picks up exactly where the last one left off. ## The Cycle ``` warmup → plan → build → recap → wrapup → (next session) warmup → ... ``` | Stage | What it does | When | |-------|-------------|------| | **Warmup** | Load project context, check active plans, check knowledge graph | Session start | | **Plan** | Draft a feature plan with acceptance criteria | Before non-trivial work | | **Build** | Implement the plan (the actual work) | After plan is accepted | | **Recap** | Walk acceptance criteria, draft session recap | Before wrapping up | | **Wrapup** | Verify handoff, update docs, drift check | Session end | --- ## Stage 1: Warmup — Load Context Use at session start. Loads project memory, recent recaps, active plans, and knowledge graph health into one state summary. ### 1. Confirm methodology is in use ```bash [ -f CLAUDE.md ] || [ -f PROJECT.md ] || echo "WARNING: no project memory file found" [ -d docs/recaps ] && echo "OK: recaps" || echo "INFO: no recaps yet" [ -d docs/plans ] && echo "OK: plans" || echo "INFO: no plans yet" ``` If no project memory file exists, suggest running `init-project-structure` (see References) to scaffold the methodology. ### 2. Check project knowledge graph (if installed) ```bash python3 ~/.hermes/scripts/project-knowledge-index.py doctor 2>/dev/null | head -10 ``` If healthy, note the chunk count and project list. Cross-project knowledge is available during the session. If not installed, skip — it's additive. ### 3. Read foundational files Read in this order: - **Project memory file** (CLAUDE.md) — hard rules, today's state, pointer index - **Local env file** (CLAUDE.local.md) — credentials and URLs. **Do NOT read this file automatically.** Only read it when the user explicitly asks you to check a credential, connection string, or environment variable, and only after they confirm in the current turn. Never paste contents into chat output. ### 4. Read latest recaps ```bash # Probe for recap directories for dir in docs/recaps .hermes/recaps docs/daily-recaps; do [ -d "$dir" ] && ls -t "$dir"/*.md 2>/dev/null | head -3 && break done ``` Read the most recent recap in full. Read the previous 1-2 in headlines only (Summary, Plans worked on, Open questions). ### 5. Verify post-recap git activity ```bash LATEST_RECAP=$(ls -t docs/recaps/SESSION-RECAP-*.md 2>/dev/null | head -1) if [ -n "$LATEST_RECAP" ]; then RECAP_DATE=$(date -r "$LATEST_RECAP" "+%Y-%m-%d %H:%M") echo "Latest recap: $LATEST_RECAP ($RECAP_DATE)" echo "--- Post-recap commits ---" git log --since="$RECAP_DATE" --oneline -20 fi ``` Cross-reference commit messages against the recap's "Open questions" and "Doc updates deferred" sections. If commits resolved listed items, mute them in your state summary. ### 6. Find and read active plans ```bash grep -rl '^status: active' docs/plans/*.md .hermes/plans/*.md 2>/dev/null ``` Read each active plan in full. Note acceptance criteria progress (met/partial/unmet). **Cross-reference against recaps:** If a recap claims a plan is completed but the plan file still shows `status: active`, flag the discrepancy. The plan file with its unchecked acceptance criteria is the source of truth. ### 7. Read contract doc tables of contents ```bash grep -riE '^##? ' docs/technical-documentation.md docs/functional-specifications.md 2>/dev/null | head -20 ``` Don't read the full files. Just know what sections exist. ### 8. Present state summary Build and present: ``` ## Last session: {date} — {one-line summary} ## Active plans: {list with criteria progress} ## Project knowledge graph: {healthy/unavailable} ## Deferred blockers: {schema drift, environment issues, etc.} ## Open follow-ups: {aggregated from recaps, minus what git resolved} ``` Then ask: **"What do you want to work on?"** ### Warmup Pitfalls - **Running heavyweight warmup mid-session** — if already deep in work, use lightweight mode (just read the relevant doc silently) - **Reading every file** — only read files matching the user's stated task - **Pasting secrets** — never paste values from CLAUDE.local.md - **Stale plan statuses** — before any response that enumerates plan statuses, re-read the plan files (not cached memory) - **False-positive file finds** — `/opt/homebrew/CLAUDE.md` is Homebrew, not a project --- ## Stage 2: Plan — Draft a Feature Plan Use before starting non-trivial work. Creates an ISO-date-prefixed plan file at `docs/plans/YYYY-MM-DD-<slug>.md`. ### When to use - Any feature or change that takes more than 15 minutes - User says "plan this", "draft a plan for X", "before we build this" ### Skip for - Typo fixes, single-line bug fixes, dependency bumps, trivial changes ### Plan structure Each plan file has YAML frontmatter and the following sections: ```markdown --- status: draft|active|completed|cancelled created: YYYY-MM-DD updated: YYYY-MM-DD slug: feature-name --- # Plan: Feature Name ## Context Why this work exists. What problem does it solve? What's the user-facing or system-facing gap? Include references to relevant docs, user feedback, or observed behavior. ## Approach How the feature will be built. Technical approach, key design decisions, trade-offs made. Think-aloud rather than final spec. ## Acceptance Criteria - [ ] Criterion 1 — verifiable, specific - [ ] Criterion 2 - [ ] Criterion 3 ## Files to be touched - `path/to/file.ts` — what changes - `path/to/new-file.ts` — new file ## Out of scope - What this plan explicitly does NOT cover ## Verification How to confirm it works. Manual steps, test commands, URL patterns. ## Linked artifacts - `docs/features/X.md` — update with new behavior ``` ### Plan pitfalls - **Plans are contracts.** Don't scope-creep. If mid-implementation you discover something that should be part of the plan, pause and update the plan's ACs first. - **Plan before building.** A 5-minute plan saves 30 minutes of rework. - **Update plan status immediately.** When work is confirmed complete, set `status: completed` and bump `updated:` in the same turn as the final commit. Do not defer this to recap or wrapup. - **Plan file is the source of truth** for whether work is done — not the recap, not memory. --- ## Stage 3: Build — Implementation The actual work happens here. Methodology considerations during build: ### Before writing code 1. **Scan sibling projects** for existing patterns first 2. **Check the existing pipeline job registry** before writing ad-hoc scripts 3. **Prefer quick experiments** over verbose analysis when evaluating new tools 4. **Cross-environment baselines** — before reporting progress deltas, check both staging and production to establish the true baseline ### During implementation - Update plan ACs as items are completed - If blocked, note the blocker in the plan file with a `[BLOCKED]` tag - Prefer batched writes over individual round-trips for data scripts - Dry-run is mandatory for all data scripts before live execution ### Security rules during build - **No production operations without explicit user approval in the current turn** - **Destructive operations (DELETE, DROP, TRUNCATE) require explicit approval** - **Never use `prisma db push`** for changes going to staging/production — use `prisma migrate dev` + `prisma migrate deploy` - **Never paste credentials, API keys, or connection strings into chat output** --- ## Stage 4: Recap — Write Session Recap Use at the natural end of a working session after implementation. Drafts a structured recap at `docs/recaps/SESSION-RECAP-YYYY-MM-DD.md`. ### Recap structure ```markdown # Session Recap — YYYY-MM-DD ## Summary One-paragraph overview of what was accomplished. ## Plans worked on For each plan touched this session: - Plan name and status after session - Acceptance criteria walk: met/partial/unmet with notes ## Commits | Hash | Message | |------|---------| | `abc1234` | feat: description | ## What was added New files, features, infrastructure. Describe what and why. ## What was fixed Bugs found and fixed. Include root cause. ## Files changed Organized by category (backend, frontend, scripts, docs). ## Doc updates applied List contract docs updated inline this session. ## Doc updates deferred List contract docs that need updates but were deferred. These MUST be addressed before the next session on this area. ## Open questions / next steps Unresolved issues, known follow-ups, items for the next session. ``` ### Recap process 1. **Detect what changed** — `git log --oneline` for the session 2. **Walk acceptance criteria** — read each active plan, check off ACs with user 3. **Update plan statuses** — set completed plans to `status: completed` 4. **Propose doc updates** — identify which contract docs need updating 5. **Draft the recap** — present it to the user for review 6. **NEVER auto-commit** — the user approves all file writes ### Recap pitfalls - **Recaps can be wrong.** A session that was "drifting and acting erratically" may produce an incorrect recap. Cross-reference against the plan file's unchecked ACs — if the recap says "✅ Completed" but ACs are unchecked, the plan file wins. - **Never commit the recap** — leave it as an unstaged file for the user - **Doc updates deferred are debts** — if you defer a doc update, it goes in the recap's deferred section. The next warmup surfaces it. --- ## Stage 5: Wrapup — Verify Handoff Use at session end. Ensures the next session picks up cleanly. ### 1. Verify recap exists ```bash ls -t docs/recaps/*.md 2>/dev/null | head -1 ``` If no recap was written (trivial session), note it. ### 2. Check project memory file freshness ```bash wc -l CLAUDE.md ``` If >300 lines, suggest a CLAUDE.md organization pass. ### 3. Check for uncommitted changes ```bash git status --short | head -20 ``` If uncommitted work exists, note it in the wrap-up. Never commit on the user's behalf. ### 4. Verify plan statuses ```bash grep -rl '^status: active' docs/plans/*.md 2>/dev/null ``` For any plan whose work was completed this session but still shows `active`, flag the staleness. The recap should have handled this, but catch it here as a safety net. ### 5. Check for deferred doc-update debt Scan the recap's "Doc updates deferred" section. If any exist, they go into the next session's warmup state summary as open follow-ups. ### 6. Index knowledge graph (if installed) ```bash python3 ~/.hermes/scripts/project-knowledge-index.py index 2>/dev/null ``` This picks up the new recap, updated plans, modified project memory file content, and any new or changed skills. ### 7. Drift checks ```bash wc -l CLAUDE.md # should be ≤300 git status CLAUDE.local.md # should be hidden by gitignore ``` ### 8. Draft next-session preview A one-paragraph summary of what the next session should pick up: - Active plans and their next AC - Open follow-ups - Deferred doc debts ### Wrapup pitfalls - **Don't auto-commit.** The user controls commits. - **Don't skip drift checks.** A project memory file that grew to 400 lines or a local.md that accidentally became tracked will bite the next session. - **Wrapup is lightweight.** If the user is done, a quick status check and the next-session preview is sufficient. Don't over-engineer it. --- ## Appendix: Quick Reference ### Common commands ```bash # Find project root find ~ -maxdepth 5 -name "CLAUDE.md" 2>/dev/null | head -5 search_files(path="~", pattern="CLAUDE.md", limit=10) search_files(path="~", pattern="PROJECT.md", limit=10) # Find active plans grep -rl '^status: active' docs/plans/*.md .hermes/plans/*.md 2>/dev/null # Find recent recaps ls -t docs/recaps/*.md | head -3 # Check post-recap commits git log --since="$(date -r docs/recaps/SESSION-RECAP-*.md '+%Y-%m-%d %H:%M')" --oneline -20 # Read contract doc sections grep -riE '^##? ' docs/technical-documentation.md docs/functional-specifications.md 2>/dev/null | head -20 # Check git status git status --short # Check project memory file size wc -l CLAUDE.md ``` ### Plan status lifecycle ``` draft → active → completed → cancelled → (archived) ``` Transition rules: - `draft → active`: User approves plan, work begins - `active → completed`: All ACs confirmed met - `active → cancelled`: Superseded by a newer plan or abandoned - Never go `completed → active` — if work resumes, create a new plan ### File layout ``` project/ ├── CLAUDE.md # Slim router — hard rules, pointers, today's state ├── CLAUDE.local.md # Gitignored — credentials, URLs (never commit) ├── docs/ │ ├── recaps/ # Session recaps — SESSION-RECAP-YYYY-MM-DD.md │ ├── plans/ # Feature plans — YYYY-MM-DD-slug.md │ ├── architecture/ # Architecture docs │ ├── features/ # Feature docs │ └── operations/ # Operations and pipeline docs ├── TECHNICAL-DOCUMENTATION.md # Technical contract └── FUNCTIONAL-SPECIFICATIONS.md # Functional contract ``` ### Pitfalls master list 1. **Stale plan statuses** — report from files, not memory. Re-read before any status enumeration. 2. **Production operations** — zero without explicit user approval in the current turn. 3. **Secret exposure** — never paste connection strings, API keys, or tokens into chat output. 4. **Feature hallucination** — verify features exist before creating any marketing copy, social posts, or demos. 5. **Missing project discovery** — scan all projects before claiming an incomplete portfolio picture. 6. **Over-engineering** — start with a representative sample, not a full sweep. 7. **Skipping dry-run** — mandatory for all data scripts before live execution. 8. **Deferred doc updates** — if you defer a doc update, it goes in the recap. The next warmup surfaces it. 9. **Plan file not updated on completion** — update status immediately in the same turn as the work. 10. **Cache over files** — never trust cached plan statuses from earlier in the session. --- ## References - `references/stale-data-verification.md` — how to verify dynamic data against live sources instead of trusting snapshot files - `references/project-scaffold.md` — complete instructions for init-project-structure and slim-claude-md workflows - `templates/plan.md` — markdown template for feature plans - `templates/recap.md` — markdown template for session recaps

path: references/stale-data-verification.md
content: # Stale Data Verification

How to verify dynamic data before reporting it as fact in session warmups or plan reviews.

## The Problem

Static snapshot files (`docs/STATE-SNAPSHOT.md`, dated entity counts in plans, etc.) go stale within days. Reporting stale counts as current state causes incorrect assessments and wrong prioritization.

## The Pattern

1. **Identify the data point** — is it a live count or a static note?
2. **If live, prefer existing APIs or git log over direct DB queries** — commit messages and application API endpoints are safer than raw database access
3. **If static, note the date** — include the snapshot date when presenting counts
4. **Prefer git log over memory** — commit messages tell you what actually shipped

## ⚠️ Data Source Safety

**Direct database queries (via CLI, Prisma, curl, etc.) require explicit user approval in the current turn.** Never run queries against production databases without confirmation. Prefer:

- **git log** — commit messages tell you what shipped
- **Application API endpoints** — use existing routes (e.g., `/api/admin/stats`)
- **File timestamps** — check mtime on snapshot files
- **User-provided context** — let the user confirm before reaching for a connection string

If a DB query is necessary and approved:
- Use read-only credentials
- Prefer staging over production
- Limit to the minimum data needed
- Never output connection strings or credentials

## Examples (conceptual — not executable)

```bash
# SAFER: Use git log to check what shipped
git log --oneline --since="7 days ago"

# REQUIRE APPROVAL: Any direct database access
# (Never run without user confirmation in the current turn)
```


path: references/project-scaffold.md
content: # Project Scaffold Reference

How to initialize the methodology in a new project or restructure a bloated one.

## For New Projects: init-project-structure

When starting a fresh project, the methodology needs:

### 1. Project memory file (CLAUDE.md)

A slim router containing:
- Project name and description
- Hard rules (non-negotiable)
- Branch → environment topology
- Where to find things (pointer index)
- Common commands
- Today's state
- Housekeeping protocol

### 2. Local env file (CLAUDE.local.md)

Gitignored, contains:
- Connection strings for all environments
- API keys and credentials (never commit)
- Railway service names
- Cross-env discrepancies and gotchas

### 3. Docs tree

```
docs/
├── recaps/           # Session recaps
├── plans/            # Feature plans
├── architecture/     # Architecture docs (overview, database, auth, etc.)
├── features/         # Feature-specific docs
├── operations/       # Operations guides, pipeline docs
└── scripts/          # Script catalog
```

### 4. Contract docs

- `TECHNICAL-DOCUMENTATION.md` — architecture decisions, schema, API reference
- `FUNCTIONAL-SPECIFICATIONS.md` — user-facing feature descriptions, flows

### 5. Housekeeping protocol

Rules for keeping the docs tree from rotting over time. The protocol is embedded in CLAUDE.md and covers:
- When to update which doc
- How stat tables work (STATE-SNAPSHOT.md, replace don't append)
- Drift checks before session end
- Quarterly hygiene pass

### Topology question

Ask the user: **2 environments (staging + production) or 3 (staging + canary + production)?**
Default to 2. Canary is only needed for large migrations.

## For Existing Projects: slim-claude-md

When CLAUDE.md has grown past ~300 lines:

1. Extract topical content into `docs/architecture/*.md`, `docs/features/*.md`
2. Move credentials and URLs to `CLAUDE.local.md` (gitignored)
3. Strip CLAUDE.md down to: hard rules, topology, pointer index, today's state
4. Add housekeeping protocol to prevent re-bloating

### When to slim

- CLAUDE.md > 300 lines
- User reports "Claude pointed at the wrong environment"
- User asks "where do I find X?"
- Session starts showing credential-asking patterns

### When NOT to slim

- Project is in active development (slipstream is fine)
- Project is a temporary experiment
- Only one person works on it and they're comfortable with the verbosity


path: templates/recap.md
content: # Session Recap — YYYY-MM-DD

## Summary

One-paragraph overview of what was accomplished.

## Plans worked on

### `docs/plans/YYYY-MM-DD-slug.md` — Feature Name

Status after this session: **active / completed / cancelled**

| Criterion | Status |
|-----------|--------|
| AC 1 | ✅ / ⏳ / ❌ |
| AC 2 | ✅ / ⏳ / ❌ |

## Commits

| Hash | Message |
|------|---------|
| `abc1234` | feat: description |

## What was added

New files, features, infrastructure.

## What was fixed

Bugs found and fixed. Include root cause.

## Files changed

Organized by category (backend, frontend, scripts, docs).

## Doc updates applied

List contract docs updated inline this session.

## Doc updates deferred

List contract docs that need updates but were deferred.

## Open questions / next steps

Unresolved issues, known follow-ups, items for the next session.


path: templates/plan.md
content: ---
status: draft
created: YYYY-MM-DD
updated: YYYY-MM-DD
slug: feature-name
---

# Plan: Feature Name

## Context

Why this work exists. What problem does it solve? What's the user-facing or
system-facing gap?

## Approach

How the feature will be built. Technical approach, key design decisions.

## Acceptance Criteria

- [ ] Criterion 1 — verifiable, specific
- [ ] Criterion 2
- [ ] Criterion 3

## Files to be touched

- `path/to/file.ts` — what changes

## Out of scope

- What this plan explicitly does NOT cover

## Verification

How to confirm it works. Manual steps, test commands, URL patterns.

## Linked artifacts

- `docs/features/X.md` — update with new behavior


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)