Skip to content

getting-started.md

Latest commit

 

History

History
98 lines (64 loc) · 5.89 KB

getting-started.md

File metadata and controls

98 lines (64 loc) · 5.89 KB
Raw

Getting started

PHARN does not scaffold your app. You create your project (e.g. with create-next-app), initialize git, then run PHARN in that directory.

Prerequisites

Requirement How PHARN checks When
Git A .git directory exists in the project root Always — checked up front, before the wizard
Stack-pack packages Every package a selected stack pack declares (via the manifest's prerequisites) is in package.json dependencies or devDependencies Only when you pick a pack that declares one — e.g. pharn-stack-nextjs requires next

.git is required for every install. Package prerequisites are conditional on your stack-pack choice: selecting None (or a pack with no prerequisites) installs without any framework package. If a check fails, the CLI prints the stack pack's own fix instructions and exits. See Troubleshooting.

PHARN works best on fresh projects. The wizard may warn (framework-neutral, git-based) when:

  • The repo has 6 or more commits — checked first; repos with 6+ commits do not also see the 2+ warning
  • The repo has 2–5 commits
  • There are 0–1 commits but more than 40 tracked files (git ls-files) — a populated repo rather than a fresh scaffold

You can continue after any warning by confirming.

Running the CLI

The npm package name is pharn-cli. It installs two equivalent commands: pharn (preferred) and pharn-cli.

npx pharn init
# same entry point
npx pharn-cli init

Quick start

npx create-next-app@latest my-app
cd my-app
npx shadcn@latest init
git init && git add -A && git commit -m "init"
npx pharn init

pharn with no subcommand runs init (same as pharn init).

The wizard

The wizard adapts to the manifest the CLI fetches. Newer manifests (schemaVersion 2) drive the per-tech questions from the manifest itself; older pinned versions (schemaVersion 1) use the original three-question flow. The CLI picks the right flow automatically.

Stack mode (schemaVersion 2)

First the CLI reads your package.json and pre-fills the wizard from the manifest's detection metadata — the stack pack (when a pack's prerequisites are all present, e.g. next → pharn-stack-nextjs) and each technology answer (when an option's detect package is present, e.g. drizzle-orm → Drizzle). What it found is shown in a note; you can override anything, and any question with no match keeps its normal default (the recommended value in Default mode, or the option marked default in Custom mode).

Then you choose a mode:

  • Default — takes the recommended stack from the manifest, overlaid with any detected answers (detection wins; undetected questions keep the recommended default), and asks no per-technology questions.
  • Custom — walks each section (database, ORM, auth, email, payments, …) with detected answers pre-selected. Options that don't apply are hidden based on earlier answers, some options are relabeled for context, and anything marked (coming soon) is shown but not selectable.

Then, regardless of mode, the wizard asks:

  1. Methodology modules — a multiselect of optional modules (pharn-pipeline, pharn-review, pharn-audits). pharn-core is always included.
  2. Stack pack — a single choice (pharn-stack-nextjs, or none), pre-selected from what was detected. The stack pack pulls in its React base automatically.
  3. Privacy posture — picks your constitution variant (gdpr-strict, standard, or minimal).
  4. Vendor skills — for technologies whose skill is published by the vendor (e.g. Supabase), the wizard records your consent to use it. On install, any consented skill with a known source is fetched automatically from the vendor's registry into .claude/skills/; a vendor with no known source yet is shown as (manual install) and recorded in pharn.config.json for you to install by hand. A vendor fetch failure is non-fatal — the rest of the install still completes.

For each answered technology, the CLI copies only the matching skill folder into .claude/skills/<skill>/ — never the sibling options you didn't pick.

Three questions (schemaVersion 1)

Against an older pinned manifest, pharn init asks just the three module/stack-pack/posture questions above.

Dependencies are resolved from the repo's manifest.json, so selecting a stack pack or any module also installs whatever it depends on.

What you get

After a successful install, your project's .claude/ contains the selected modules merged together:

Artifact Description
commands/, skills/, rules/, hooks/ The slash commands and logic for your chosen modules
skills/<skill>/ The per-technology skills selected in the wizard (schemaVersion 2)
ai_docs/, templates/, … Stack-pack reference docs and templates
memory-bank/ Markdown files that persist project context across sessions
CONSTITUTION.md Your chosen constitution variant
pharn.config.json skillsVersion, commit SHA, installed modules, constitution variant, and (schemaVersion 2) your stack answers + installed skills

See pharn.config.json for the exact schema.

After init

  1. Open Claude Code in the project directory.
  2. Run /pharn-plan to plan your first feature. For a fuzzy or larger feature, run /pharn-spec first to pin the intent and scope — it's optional and feeds /pharn-plan.

The day-to-day loop: /pharn-plan → /pharn-grill → /pharn-build → /pharn-regress → /pharn-verify → /pharn-review → /pharn-ship (prepend /pharn-spec for features whose scope needs nailing down first).

Next steps