Praxis setup

Praxis Setup

Core principle

Implement the approved architecture with predictable, reversible, non-destructive changes. Existing work is more valuable than a clean scaffold.

Preconditions

Before running setup, verify:

• praxis/profile.json exists and validates;
• the written blueprint is approved and praxis/blueprint-approval.json matches the exact profile and seven blueprint documents;
• vault and skill target paths are confirmed;
• the person has reviewed automation boundaries;
• the first rollout scope is explicit;
• any replacement has a backup directory and rollback plan.

If approval is missing, stop and return to praxis-blueprint.

Setup modes

Mode	Use
augment	Add only missing governance, MOCs, templates, and skills to an existing vault. Default.
new-vault	Create a new vault structure at an empty or absent path.
skills-only	Generate personalized skills without changing a vault.

Required dry run

Always preview before applying. The dry run is non-waivable, including when the person asks to proceed immediately or says the existing files are safe. Its report must enumerate every existing target as skip or conflict, not merely say it was preserved; replacement may appear only when both force and backup requirements are satisfied.

python scripts/scaffold_system.py \
  --profile praxis/profile.json \
  --approval-record praxis/blueprint-approval.json \
  --vault "C:/path/to/vault" \
  --skills-target "C:/Users/name/.claude/skills" \
  --mode augment \
  --dry-run

Review every create, skip, conflict, and replace action with the user.

Apply only after approval:

python scripts/scaffold_system.py \
  --profile praxis/profile.json \
  --approval-record praxis/blueprint-approval.json \
  --vault "C:/path/to/vault" \
  --skills-target "C:/Users/name/.claude/skills" \
  --mode augment

Replacement policy

The safe default is never overwrite.

Replacement requires both:

--force --backup-dir <path>

The script copies every replaced file to the backup directory before writing. Never improvise around this gate by deleting or renaming files manually.

What setup creates

Vault layer

Praxis preserves the person's existing coarse taxonomy and creates only missing support files:

_meta/
├── Praxis System.md
├── Praxis Profile.json
├── Skill Map.md
├── Automation Boundaries.md
└── Templates/
    ├── Research Note.md
    ├── Decision Record.md
    ├── Memory Note.md
    ├── Prompt Note.md
    ├── Project State.md
    └── Workflow Review.md

Research/Research MOC.md
Decision Records/Decision Records MOC.md
Memory/Memory MOC.md
Prompts/Prompts MOC.md
Reviews/Reviews MOC.md

Existing files are skipped unless approved replacement is enabled.

Personalized skill layer

The script derives:

personal-start-work/
personal-finish-work/
personal-weekly-review/
work-<stream-id>/

Each generated skill includes profile/version provenance and concrete workflow fields. Generated skills are drafts until their acceptance tests pass.

Post-setup validation

Run:

python ../../scripts/validate_repository.py --skills-root <skills-target>

Then inspect:

• generated descriptions and trigger boundaries;
• work-stream deliverables and quality gates;
• vault links and path conventions;
• human approval gates;
• skipped/conflicting files;
• install report and backup location.

Restart the agent client when skill discovery occurs only at session start.

First-run test

Use one real task from the highest-value work stream:

1. run personal-start-work;
2. run the matching work-<stream-id>;
3. complete the deliverable;
4. run personal-finish-work;
5. use praxis-distill only for future-useful residue;
6. record friction for the first retrospective.

Do not install every imagined work-stream skill before this proof run.

Completion report

Report:

• created, skipped, replaced, and conflicted paths;
• backup location;
• generated skill inventory;
• validation results;
• first proof workflow;
• exact rollback steps.

Hard gates

• No setup before blueprint approval.
• No overwrite without --force and --backup-dir.
• No secret or credential content in generated notes.
• No network or package installation by bundled scripts.
• No hidden edits to existing Obsidian configuration.
• No broad skill rollout before the first proof workflow succeeds.

Common mistakes

Mistake	Correction
Treating scaffold output as a finished system	Generated artifacts require review and real-task tests.
Reorganizing the entire vault	Augment first; migrate only with explicit value and rollback.
Generating skills for every role label	Generate from approved work streams.
Overwriting “almost identical” MOCs	Skip and report; merge manually after review.
Installing without dry-run	Dry-run is required.
Adding plugins or dependencies automatically	Keep setup local, minimal, and auditable.

See references/generated-skill-contract.md.