Place CLAUDE.md at your repository root. Claude reads it automatically — no command or plugin installation required. At minimum, set three fields:

• type: java — routes commit, review, and health workflows to Java-specific skills
• GitHub repo: owner/repo — enables issue linkage in commits and gh commands
• ## Work Tracking / Issue tracking: enabled — activates automatic issue creation before code is written

Additional fields you can add: Main branch: main, build commands under ## Build, and custom instructions under ## Custom. These feed into the git-commit skill's automated checks.

A minimal Java project CLAUDE.md looks like this:

## Project

**type:** java
**GitHub repo:** acme/orders-service
**Main branch:** main

## Work Tracking

**Issue tracking:** enabled

Once this file exists, every /java-git-commit run reads it to enforce issue linkage, choose the right review workflow, and sync DESIGN.md if you are on an epic branch.

You can start with Option A and add a workspace later — /workspace-init migrates existing artifacts. The rest of this guide works either way.

cc-praxis supports three workspace modes:

• Project-only — no workspace; all artifacts stay inside the project repo
• Project + workspace — companion repo at ~/claude/private/<project>/ for private working documents
• Alternative path — you specify a custom path for teams with shared drives or existing structures

A workspace created by /workspace-init contains these directories:

• adr/ — Architecture Decision Records
• snapshots/ — immutable design snapshots (auto-pruned to 10)
• blog/ — project diary entries before they are published
• specs/ — brainstorming specs and planning documents
• design/JOURNAL.md — append-only journal auto-written by java-git-commit on epic branches
• HANDOFF.md — current session handover document

Routing is configured once in the workspace CLAUDE.md with three keywords: project · workspace · alternative ~/path/. Skills read this at runtime to decide where artifacts land.

The priority order matters: a fast implementation with a resource leak is worse than a slower one without. java-dev enforces this by checking safety before suggesting optimisations.

Key patterns it applies:

• try-with-resources for every closeable (streams, connections, PreparedStatements)
• Thread ownership comments on any field accessed from multiple threads
• Quarkus CDI — @ApplicationScoped beans are singletons; document if state is intentional
• Panache — prefer find("field", value) over raw HQL for simple queries
• RESTEasy Reactive — return Uni<Response> not Response from reactive endpoints

When called on a Quarkus REST endpoint, java-dev scaffolds the full slice: resource class, service, repository, and a passing @QuarkusTest integration test.

java-code-review runs automatically before /java-git-commit if no review has been done in the current session. You can also invoke it directly at any point.

What the three tiers mean:

• CRITICAL — the commit is blocked until fixed. Examples: resource leak, unchecked exception swallowed, SQL injection risk, secrets in code.
• WARNING — should be fixed before merging but won't block the current commit.
• NOTE — suggestions for readability, naming, or minor quality improvements.

When security-sensitive code is found (anything touching authentication, authorisation, payments, or personally identifiable information), the skill offers to chain to java-security-audit for a dedicated OWASP pass before the commit proceeds.

Always use /java-git-commit instead of plain git commit. Plain commits bypass the review, design sync, and issue linkage checks.

Java commit scopes the skill recognises and enforces:

• rest — REST resources and DTOs
• service — business logic and service classes
• repository — Panache repositories and data access
• migration — Flyway or Liquibase database migrations
• config — application.properties and configuration
• test — unit and integration tests

On an epic branch, the skill writes a journal entry to design/JOURNAL.md using §SectionName anchors rather than committing directly to DESIGN.md. DESIGN.md is only updated when the epic closes.

The six-phase flow:

1. Context — Claude reads CLAUDE.md, DESIGN.md, and relevant code to understand the current state
2. Questions — asks clarifying questions before proposing anything
3. Approaches — presents multiple design options with tradeoffs
4. Design — develops the chosen approach in depth
5. Spec — writes a formal spec document to docs/superpowers/specs/
6. Plan — produces a phased implementation plan ready to execute via /executing-plans or /subagent-driven-development

The hard gate at phase 5 means Claude will not write implementation code until you explicitly approve the spec. This prevents the common failure mode of starting implementation before the design is clear.

idea-log uses three statuses:

• active — worth revisiting; no decision yet
• promoted — became an ADR, spec, or GitHub issue
• discarded — explicitly ruled out with a reason

Entries older than 90 days without a status change are flagged as stale. This keeps IDEAS.md from becoming a graveyard.

ADRs are append-only in MADR format. Once accepted, the decision record is never edited — only superseded by a later ADR. Statuses progress: Proposed → Accepted → Deprecated → Superseded.

Run /issue-workflow once (Phase 0) to configure labels, milestones, and the CLAUDE.md Issue tracking: enabled flag. After that, Phases 1–3 run automatically:

• Phase 1 — when you say "implement", "start coding", or "execute the plan", Claude creates a GitHub epic and child issues before writing any code
• Phase 2 — before writing any code, Claude checks that an active issue exists. If not, it drafts one and checks whether it belongs to an existing epic
• Phase 3 — at commit time, Claude confirms issue linkage (Refs #N or Closes #N) and suggests splitting if staged changes span multiple concerns

All commits reference an issue. If you explicitly want to skip issue linkage for a specific commit, say so — Claude will confirm once before proceeding.

JOURNAL.md is created by /epic and auto-appended by /java-git-commit on every commit during an epic. It uses §SectionName anchors that match DESIGN.md section headings, so the three-way merge at epic close can route journal entries to the correct sections of DESIGN.md.

Snapshots have five standard sections: Summary, Architecture, Data Model, Open Questions, and Next Steps. They are immutable — once written, never edited. The 10-snapshot limit keeps the snapshots/ directory manageable without manual cleanup.

Use a snapshot before any change that is hard to reverse: repository layer refactors, schema migrations, switching frameworks, or changing public API contracts.

The three-way merge that /epic performs when closing:

1. Baseline SHA — captured by /epic when the epic began, so Claude knows exactly what state DESIGN.md was in
2. Current DESIGN.md — may have received direct edits during the epic
3. JOURNAL.md entries — routed by §SectionName anchor into the matching DESIGN.md section

After merging, /epic posts all specs from specs/ and ADRs created during the epic to the GitHub issue as comments, then closes the issue. It then offers to delete the epic branch and the workspace's companion branch.

Run it only when the epic is truly complete — it is not reversible once branches are deleted and the issue is closed.

The wrap checklist /handover executes:

• write-blog — captures today's narrative in the project diary
• update-claude-md — syncs any new conventions or commands discovered this session
• forage sweep — scans the session for gotchas, non-obvious techniques, and undocumented behaviours to preserve in the technical garden

HANDOFF.md is delta-first: unchanged sections carry a git reference rather than full content, keeping the file short. The freshness check at the start of any session is: git log -1 --format="%ar" -- HANDOFF.md. If it is more than a day old, treat it as stale and run a new handover before starting work.

The forage sweep is the most valuable part for long-running projects — it captures the tacit knowledge that doesn't make it into commit messages or design docs.

Entry metadata uses two fields: entry_type: article | note and subtype: diary. When published to the Jekyll site, diary entries appear under /blog/ and articles under /articles/ — that filtering is done by the Jekyll page templates. publish-blog handles cross-posting entries to external platforms.

The skill reads a writing style guide from $PERSONAL_WRITING_STYLES_PATH if set, or falls back to a bundled default. The guide controls vocabulary, register, heading style, and what to avoid — so entries written by Claude match your actual voice rather than sounding generic.

What good diary voice looks like — an honest account of a session:

Started confident. The migration looked straightforward — just move the query from the service to a dedicated repository class. Forty minutes later I was staring at a Panache query that returned the right rows in the test database and wrong ones in production, and the only difference I could find was the Hibernate dialect version. Took another hour to realise the column name mapping was case-sensitive in one and not the other. Not a fun bug. But now we have a regression test for it, and the repository layer is cleaner for the trouble.

Run /write-blog with no arguments to do a retrospective sweep of git history and draft multiple entries. Run it with context ("write a blog entry for today's session") to draft a single entry for the current session.