Part 2 — Building Blocks

your-project/
├── CLAUDE.md                              ← always loaded, every session
└── .claude/
    ├── commands/                           ← workflows (wor-*) + commands (com-*)
    │   ├── wor-content-pipeline.md         ← multi-step orchestration
    │   └── com-publish-article.md          ← atomic user action
    ├── agents/                             ← specialist (age-spe-*) + supervisor (age-sup-*)
    │   ├── age-spe-researcher.md           ← domain specialist
    │   ├── age-spe-writer.md
    │   └── age-sup-editor.md               ← validates output quality
    ├── skills/                             ← reusable capabilities (ski-*)
    │   ├── ski-format-output/
    │   │   └── SKILL.md                    ← skill entry point
    │   └── ski-weekly-report/
    │       └── SKILL.md
    ├── rules/                              ← behavioral constraints (rul-*)
    │   └── rul-citation-standards.md       ← structured: Context + Hard/Soft Constraints
    ├── knowledge-base/                     ← reference material (kno-*)
    │   ├── kno-style-guide.md
    │   └── kno-api-reference.md
    ├── resources/                           ← support docs extending entities (res-*)
    │   └── res-api-full-reference.md       ← loaded conditionally by agents
    ├── scripts/                             ← executable automation (scp-*)
    │   └── scp-lint-check.sh               ← .sh or .py in Claude Code
    ├── hooks/                               ← hook documentation (hok-*)
    │   └── hok-auto-lint.md                ← what the hook does and why
    ├── settings.json                        ← hook config, permissions, tool restrictions
    └── settings.local.json                  ← CC-exclusive permission overrides

# Project: Content Pipeline

## Purpose
Automated system for researching, writing, and publishing articles.
Output language: English. Audience: senior professionals.

## Active Agents
| Agent | Trigger | Owns |
|---|---|---|
| @age-spe-researcher | Any research or fact-finding task | /research/ |
| @age-spe-writer | Draft creation from research | /drafts/ |
| @age-sup-editor | Review, scoring, final approval | /output/ |

## Rules
- Never modify files outside the agent's own directory
- All drafts must include a source citation for every factual claim
- Instead of deleting files, move them to /archive/ with today's date
- For detailed citation rules, see `.claude/rules/rul-citation-standards.md`

## Conventions
- Entity names: prefixed by type (age-spe-, ski-, rul-, etc.)
- File names: kebab-case, no spaces
- Dates: ISO 8601 (YYYY-MM-DD)

---
name: age-spe-researcher
description: Researches topics using web search and synthesizes structured
  summaries with citations. Use for any information gathering, fact-checking,
  competitive analysis, or background research task.
model: sonnet
tools: WebSearch, Read, Grep
permissionMode: default
memory: project
---

---
name: age-sup-code-reviewer             # prefix: age-sup- (supervisor)
description: Reviews pull request diffs for correctness, security issues,
  test coverage, and style guide compliance. Use when a PR is ready for
  review or when asked to check code quality on any file.
model: sonnet                           # fast enough for review tasks
tools: Read, Grep, Glob                 # read-only — never modifies files
permissionMode: default                 # asks before any action
memory: project                         # remembers team preferences across sessions
---

You are a senior code reviewer. Your job is to catch bugs, security
vulnerabilities, and style violations — not to rewrite working code.

## Review Process
1. Read the diff or files provided
2. Check for: logic errors, security issues, missing error handling,
   test coverage gaps, style guide violations
3. For each issue found, state: file + line, severity (critical/major/minor),
   explanation, suggested fix

## Output Format
### Summary
[One paragraph: overall quality assessment]

### Issues Found
| Severity | File | Line | Issue | Suggestion |
|---|---|---|---|---|

### Approved?
[Yes / No / Yes with minor issues]

## Rules
- Never suggest rewriting code that works correctly
- Flag security issues as critical regardless of other quality
- If no issues found, say so explicitly — don't manufacture concerns

---
name: age-spe-competitive-analyst
description: Analyzes competitors using public web sources and returns
  structured reports. Use for market research, competitive positioning,
  feature comparison, or pricing intelligence tasks.
model: opus
tools: WebSearch, Read
permissionMode: default
memory: project
---

You are a competitive intelligence specialist. Your outputs are
structured for executive review — factual, sourced, and actionable.

## Analysis Framework
For each competitor requested:
1. Company overview (size, funding, positioning)
2. Product features vs. ours (table format)
3. Pricing model and tiers
4. Recent news and strategic moves (last 6 months)
5. Threat level: Low / Medium / High — with justification

## Rules
- Only cite verifiable public sources — no speculation
- Always include the URL and date for every claim
- If data is unavailable, say so — don't estimate

---
name: age-spe-doc-writer
description: Generates technical documentation from code, comments,
  and specifications. Use for README files, API docs, changelog entries,
  or any documentation task.
model: sonnet
tools: Read, Write, Grep, Glob
permissionMode: acceptEdits
---

You are a technical writer specializing in developer documentation.

## Principles
- Clarity over completeness — one clear sentence beats three vague ones
- Show, don't tell — every concept gets a code example
- Audience: developers who are busy. Front-load the most important info.

## Output
- Write in active voice
- Use second person ("you", "your")
- Code examples must be runnable, not pseudocode

.claude/skills/
└── ski-pr-review/
    ├── SKILL.md             ← entry point
    ├── checklist.md         ← referenced template
    └── examples/
        └── good-pr.md       ← example for Claude to learn from

---
name: ski-pr-review
description: Runs the team PR review checklist on the current branch diff.
  Checks correctness, security, test coverage, and style. Invoke with
  /ski-pr-review or when asked to review a pull request.
user-invocable: true
allowed-tools: Read, Grep, Bash
---

# PR Review Skill

Run our standard PR review process on the provided diff or branch.

## Steps
1. Read the diff: `!git diff main...HEAD`
2. Load the review checklist from `checklist.md`
3. Evaluate each checklist item against the diff
4. Generate a structured review report

## Output Format
Use the template in `checklist.md`. Return the completed checklist
plus a Summary and Verdict (Approve / Request Changes / Needs Discussion).

---
name: summarize
description: Summarizes a document or URL into key points.
user-invocable: true
---

Summarize the following: $ARGUMENTS

Return:
- 3-sentence overview
- 5 key points as bullets
- Any action items or decisions

---
name: weekly-report
description: Generates the team's weekly status report from Git history,
  Jira tickets, and notes. Run every Friday. Invoke with /weekly-report.
user-invocable: true
allowed-tools: Read, Bash, Grep
---

# Weekly Report Skill

Generate this week's team status report.

## Data Collection
1. Pull this week's commits: `!git log --since="7 days ago" --oneline`
2. Read any notes in `/notes/this-week.md` if it exists
3. Check `/projects/` for files modified this week: `!find projects/ -newer projects/ -name "*.md"`

## Report Structure
Generate a Markdown report with:

### This Week
[What shipped, what was completed]

### Next Week
[What's planned]

### Blockers
[Anything blocking progress]

### Metrics
[Any numbers worth tracking]

Save the report to `/reports/YYYY-MM-DD-weekly.md`

---
name: competitor-scan
description: Deep research on a competitor. Forks into Explore mode
  to avoid polluting the main session context.
user-invocable: true
context: fork
agent: Explore
allowed-tools: WebSearch, Read
---

Research $ARGUMENTS as a competitor. Cover:
1. Product overview and positioning
2. Pricing tiers
3. Key differentiators vs. our product
4. Recent news (last 3 months)
5. User sentiment (reviews, social)

Return a structured report saved to `/research/competitors/$ARGUMENTS.md`

.claude/commands/
├── wor-content-pipeline.md       ← workflow (multi-step orchestration)
├── com-deploy-staging.md         ← command (atomic action)
├── com-export-system.md
└── com-publish-version.md

---
description: Deploys the current branch to the staging environment.
  Runs tests, builds, and pushes to staging via the deploy script.
  Use with /deploy-staging before requesting a production review.
---

# Command: Deploy to Staging

Run the full staging deployment pipeline for the current branch.

## Behavior
1. Run the test suite: `!npm test`
2. Build the project: `!npm run build`
3. Execute the deploy script: `!bash scripts/deploy-staging.sh`
4. Report the deployed URL and any warnings

## Expected Output
A confirmation message with:
- Deployed URL
- Build duration
- Any test warnings

## Constraints
- Never deploy if tests fail — stop and report the failures
- Never deploy the `main` branch to staging — staging is for feature branches only
- If the deploy script exits non-zero, report the error verbatim

---
description: Exports the current project as a standalone git repository.
  Initializes version tracking, creates initial commit, and optionally
  pushes to GitHub. Use with /export-system after completing a build.
---

# Command: Export System

Initialize this project as its own independent Git repository.

## Behavior
1. Validate that the project directory contains the expected structure
2. Initialize a Git repo if one doesn't exist
3. Create a `.gitignore` for temporary and sensitive files
4. Create a `VERSION` file set to `0.1.0`
5. Make an initial commit and tag it `v0.1.0`
6. If `gh` CLI is available, offer to create a private GitHub repo

## Expected Output
Confirmation with:
- Repository path
- Initial version tag
- GitHub URL (if created)

## Constraints
- Never overwrite an existing Git repository — if `.git/` exists, stop and warn
- Never commit files matching `.env*` or `*credentials*`

---
description: Translates the content of a file or selection to a target
  language while preserving formatting and code blocks. Use with
  /quick-translate <language> to translate the current selection.
---

# Command: Quick Translate

Translate the provided content to $ARGUMENTS while preserving:
- All Markdown formatting
- Code blocks (leave code untranslated)
- Links and references

## Behavior
1. Identify the target language from `$ARGUMENTS`
2. Translate all human-readable text
3. Preserve technical terms, proper nouns, and code snippets
4. Return the translated content in the same format

## Expected Output
The full translated content, ready to paste or save.

## Constraints
- Never translate code, variable names, or file paths
- If no target language is specified, ask the user before proceeding
- Maintain the original document structure exactly

## Context

This rule ensures that all generated output follows the organization's
brand guidelines. Without it, agents produce inconsistent formatting
that requires manual correction.

## Hard Constraints

- Never use first person in customer-facing content.
- Never exceed 80 characters per line in code comments.
- Never commit files without running the linter first.

## Soft Constraints

- Prefer active voice over passive voice.
- Use tables for structured comparisons instead of bullet lists.
- Keep function names under 30 characters when possible.

## Rules

### File Modifications
- Never modify files outside the agent's designated directory
- Instead of deleting, move to /archive/YYYY-MM-DD/
- All new files go in the appropriate module directory — never at project root

### Code Style
- Functions: under 40 lines. Extract helpers rather than growing functions.
- Variable names: descriptive, no single letters except loop counters
- Instead of comments explaining what, write code that explains itself

### Output
- All agent outputs in Markdown unless the user requests another format
- Tables preferred over bullet lists for structured comparisons

.claude/knowledge-base/
├── kno-style-guide.md       ← brand voice, tone, formatting rules
├── kno-api-reference.md     ← internal API endpoints and parameters
├── kno-error-codes.md       ← known errors and resolution steps
└── kno-domain-glossary.md   ← product and industry terminology

When writing any customer-facing content, read `kno-style-guide.md`
for tone, vocabulary, and formatting requirements.

If you encounter an API error, check `kno-error-codes.md` before
attempting a workaround.

.claude/resources/
├── res-api-full-reference.md    ← detailed API specs (loaded conditionally)
├── res-deployment-checklist.md  ← extended deployment procedures
└── res-interview-questions.md   ← question trees for discovery

# Agent instructions (in the agent .md file)

For standard tasks, use the short API summary below.
For complex API usage or if you encounter a FooBarError,
read `res-api-full-reference.md` in `.claude/resources/`.

## Quick API Reference
POST /items — create item (body: {name, type})
GET  /items/{id} — get item by ID
DELETE /items/{id} — delete item (requires admin role)

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/lint.sh",
            "timeout": 30
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude finished\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

.claude/hooks/
├── hok-auto-lint.md           ← documents the PostToolUse lint hook
└── hok-safety-check.md        ← documents the PreToolUse safety hook

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "prompt",
          "prompt": "Before running this command, confirm it won't cause irreversible changes. If it could delete data or modify production, stop and ask the user."
        }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{
          "type": "command",
          "command": "npx prettier --check $CLAUDE_FILE_PATH 2>/dev/null || true",
          "timeout": 10
        }]
      }
    ],
    "Stop": [
      {
        "matcher": ".*",
        "hooks": [{
          "type": "command",
          "command": "echo 'Task complete' | terminal-notifier -title 'Claude Code'",
          "timeout": 5
        }]
      }
    ]
  }
}

.claude/scripts/
├── scp-lint-check.sh          ← shell script for linting
├── scp-validate-schema.py     ← Python validation script
└── scp-deploy-staging.sh      ← deployment automation

#!/bin/bash
# scp-validate-structure.sh
# Validates that the project follows the expected directory structure

REQUIRED_DIRS=("agents" "skills" "rules" "knowledge-base")
MISSING=()

for dir in "${REQUIRED_DIRS[@]}"; do
  if [ ! -d ".claude/$dir" ]; then
    MISSING+=("$dir")
  fi
done

if [ ${#MISSING[@]} -gt 0 ]; then
  echo "Missing directories: ${MISSING[*]}"
  exit 1
fi

echo "Structure valid."
exit 0