From howl-pa
Two-pass first-principles project seeding methodology for greenfield or brownfield work. Trigger when the user is kicking off a new project, starting significant work on an existing codebase, or asking for a structured plan before execution. Triggers on phrases like "seed this project", "how should I start", "plan before I code", "kick off", "greenfield", "brownfield", "decompose this goal", "what's my plan", or any request to produce a project plan, architecture plan, or execution plan from a stated goal. Produces FOUNDATIONS.md or LANDSCAPE.md (forward pass), PLAN.md (backward pass), and a reconciled execution task list. Does not write code until after user sign-off.
How this skill is triggered — by the user, by Claude, or both
Slash command
/howl-pa:project-seedingThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Howl PA's seeding protocol. Every non-trivial project or significant codebase change flows through this skill before any code is written. It splits reasoning into a *forward pass* (what is true) and a *backward pass* (what must be true for the goal to exist), then reconciles the two before execution.
Howl PA's seeding protocol. Every non-trivial project or significant codebase change flows through this skill before any code is written. It splits reasoning into a forward pass (what is true) and a backward pass (what must be true for the goal to exist), then reconciles the two before execution.
Skip and just do the work when:
Establish what is true before reasoning about the goal. No goal-oriented reasoning yet.
Greenfield → write FOUNDATIONS.md.
HARD (non-negotiable: language runtime, paid-vs-free constraint, regulatory limit, hardware) or SOFT (default, preference, convention, reversible choice)- HARD: Node >=22 (node:sqlite requirement) / - SOFT: Prefer grammy over telegraf for Telegram (team familiarity)Brownfield → write LANDSCAPE.md.
FUNDAMENTAL — load-bearing, removing it breaks the system (DB schema, auth, core routing, main entry)FOSSIL — historical artifact, no longer active, safe to delete or refactor around (dead code path, unused table, commented-out flag, old migration)CONVENTION — works today but could be replaced without losing behavior (logger choice, linter config, naming style, folder layout)- FUNDAMENTAL: <persistence module> — every subsystem reads/writes through it / - FOSSIL: <old path> — zero callers, superseded by <new path> in commit <sha> / - CONVENTION: <logger of choice> — any structured logger would substituteHard rule: stop after ~1,500 words. Reference document, not essay. Links to code over prose.
Checkpoint: present classifications to user. Wait for sign-off before Phase 2. For brownfield, explicitly flag: component classifications require human review — the agent lacks domain and historical context, so every FOSSIL tag is a hypothesis to be confirmed, not a fact.
Starting from the stated deliverable, recursively ask "what must be true for this to exist?" Do not write code. Write PLAN.md.
FOUNDATIONS.md or LANDSCAPE.mdFACT — directly supported by foundations or observable realityDESIGN-CHOICE — reversible decision being made now; note the alternative consideredASSUMPTION — belief that is load-bearing but unverified; these are the dangerous onesPLAN.md:
Hard rule: no code. Not even pseudocode more than 3 lines. If you catch yourself sketching an implementation, move it to Open Questions.
This is a loop, not a one-shot diff. Forward and backward passes are rarely consistent on the first try. Iterate until every mismatch is either resolved (plan amended, foundation added, or explicitly rejected with a reason) or escalated to an Open Question the user must answer. A single pass that still contains unresolved gaps has not satisfied this phase.
Each iteration writes or updates RECONCILIATION.md with a small number of findings. The document is append-only: each cycle adds a new ## Cycle N — <date> section so you can audit how the plan converged.
Iteration loop:
FOUNDATIONS.md/LANDSCAPE.md against PLAN.md. Catalog every mismatch and classify each one:
claude-mem is available but plan re-implements session memory).SOFT: Prefer grammy without saying what the alternative is).FOUNDATIONS.md/LANDSCAPE.md if a missing or fuzzy foundation is what's breaking alignment.PLAN.md if the decomposition had an unsupported assumption or an over-reach.Open Questions section of PLAN.md with a proposed next step.PLAN.md either traces to a FACT in FOUNDATIONS.md/LANDSCAPE.md, is a clearly-tagged DESIGN-CHOICE with a stated alternative, or is explicitly an ASSUMPTION the user has signed off on.HARD foundation either gets exploited somewhere in PLAN.md or is documented as "intentionally unused this pass" in RECONCILIATION.md.Record in each cycle: mismatches opened, mismatches closed, edits made, remaining gaps. When a cycle closes zero new gaps but opens new ones, pause and show the user — the goal is monotonic convergence, not churn.
Hard rule: no phase-4 execution until the loop has converged on a cycle that opened zero new gaps and left zero unparked mismatches. "We'll figure this out during implementation" is exactly the analogy-masquerading-as-first-principles trap this phase exists to catch.
Checkpoint: user reviews the full RECONCILIATION.md history (every cycle) and the final state of FOUNDATIONS.md + PLAN.md. Signs off explicitly. Only then does Phase 4 begin.
Only after Phase 3 sign-off. Produce an ordered task list (in PLAN.md under ## Execution or a separate TASKS.md).
PLAN.md and the enabling foundation in FOUNDATIONS.md / LANDSCAPE.md- [ ] <task> — from PLAN.md §<n>, relies on FOUNDATIONS §<n>After this phase, and only this phase, implementation begins.
touch file.ts. Exploratory reads are fine; writes to source are forbidden until Phase 4 begins.FACT, DESIGN-CHOICE, or ASSUMPTION, it is not yet fit for the plan.FOUNDATIONS.md and LANDSCAPE.md cap at ~1,500 words each. They are indexes, not narratives. Link to code; don't transcribe it.PLAN.md must answer: what would falsify this plan? This is the primary defense against analogy-based reasoning pretending to be first principles.FOSSIL and CONVENTION classification in LANDSCAPE.md is a hypothesis. Surface them explicitly for user review. The agent cannot know intent from code alone.FOUNDATIONS.md/LANDSCAPE.md, PLAN.md, optional RECONCILIATION.md, TASKS.md) are written to a single directory chosen at the start of Phase 1 (see Output locations below) and committed with a [mc] seed: prefix when inside the vault. Future sessions rebuild context from these, not from chat.Pick the destination once at the start of Phase 1 and keep all four artifacts together:
08_Pipeline/ideas/<YYYY-MM-DD>-<slug>/index.md (see src/vault.ts and src/vault-writer.ts). Additional seed artifacts co-locate in that same directory./open <slug> promotion — the whole pipeline directory is renamed into 06_Projects/6N_<PascalName>/ (see src/idea-open.ts). Artifacts move with it; no separate seeds subfolder is created.All writes inside the vault are committed by the bot with a [mc] seed: <path> message so they flow into obsidian-git without conflict.
08_Pipeline/ideas/... and the user (or a CC agent session) invokes this skill against that seed later to produce the full four-artifact plan.codex-arch, codex-research, or codex-route. As of now there is no automatic wiring between this skill and those agents; delegation happens when the user or the orchestrating session explicitly spawns one. Treat it as a documented hand-off point, not an active pipeline.vault-indexer.ts scans the whole projecthowl vault on the vault-reindex schedule. Any artifact written inside the vault (including seeds under 08_Pipeline/ideas/ or 06_Projects/6N_*/) becomes visible to recall() within one reindex cycle. Artifacts written outside the vault (e.g., inside another repo) are not indexed.Guides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub sannidhyas/howl-pa --plugin howl-pa