project-seeding

Project Seeding — Two-Pass First-Principles Methodology

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.

When to use

• New project / repo / service (greenfield)
• Significant work on existing codebase — new subsystem, architectural change, large refactor, feature spanning multiple modules (brownfield)
• Any explicit request for a project plan, architecture plan, or execution plan from a stated goal
• User says: "seed this project", "how should I start", "plan before I code", "kick off", "decompose this goal", "what's my plan"
• User says: "forward-backward thinking", "zero to hero", "illuminate the path", "reconcile plan and foundations"

When NOT to use

Skip and just do the work when:

• Trivial change — one file, one symbol, one typo
• Single bug fix with a known root cause
• Cosmetic edits (rename variable, format, move import)
• User explicitly says "skip planning", "just do it", "fast path"
• Work clearly inside a single well-defined function or config

Workflow

Phase 1 — Forward pass (bedrock)

Establish what is true before reasoning about the goal. No goal-oriented reasoning yet.

Greenfield → write FOUNDATIONS.md.

• Enumerate facts, constraints, capabilities available
• Each entry tagged HARD (non-negotiable: language runtime, paid-vs-free constraint, regulatory limit, hardware) or SOFT (default, preference, convention, reversible choice)
• Sections: Runtime, Dependencies available, External services/APIs available, Budget/licensing, Team/time, Conventions inherited
• Example entry: - HARD: Node >=22 (node:sqlite requirement) / - SOFT: Prefer grammy over telegraf for Telegram (team familiarity)

Brownfield → write LANDSCAPE.md.

• Walk the codebase with Glob + Grep + Read. Do not modify anything.
• Classify every significant component into one of three buckets with a one-line reason:
  • 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)
• Sections: Entry points, Data model, External boundaries, Core logic, Ancillary (scripts, docs, config)
• Example shape (illustrative, not about this repo): - 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 substitute

Hard 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.

Phase 2 — Backward pass (decomposition)

Starting from the stated deliverable, recursively ask "what must be true for this to exist?" Do not write code. Write PLAN.md.

• Root node = the deliverable, stated in one sentence
• Each child = a precondition that must hold for the parent to be possible
• Stop recursion at:
  • Concrete action — a task a person or agent can execute directly
  • Known primitive — something already present in FOUNDATIONS.md or LANDSCAPE.md
  • Unknown — question that can't be answered without more info; route to Open Questions
• Tag every node:
  • FACT — directly supported by foundations or observable reality
  • DESIGN-CHOICE — reversible decision being made now; note the alternative considered
  • ASSUMPTION — belief that is load-bearing but unverified; these are the dangerous ones
• Required sections in PLAN.md:
  1. Goal (one sentence)
  2. Decomposition tree (nested bullets with tags)
  3. Open Questions (every unknown surfaces here with a proposed next step)
  4. What would falsify this plan? — list conditions under which the plan collapses. Forces a check against analogy-based reasoning masquerading as first principles. (e.g., "If the OAuth quota is lower than assumed, the polling cadence in §3.2 fails.")

Hard rule: no code. Not even pseudocode more than 3 lines. If you catch yourself sketching an implementation, move it to Open Questions.

Brownfield / large codebases (>5 modules): Delegate the backward-pass walk to codex-corps:codex-arch (design-heavy decomposition) or codex-corps:codex-research (read-only spelunking) before writing PLAN.md. Not mandatory for small repos — use judgment.

DESIGN-CHOICE nodes — council escalation: When a node is tagged DESIGN-CHOICE and the alternative is non-obvious, invoke the council skill (sibling skill at claude-plugin/skills/council/) to get multi-backend deliberation (Claude + Codex + local Ollama) before locking the choice. Do NOT invoke council for every decision — only when the model itself flags "non-obvious alternative."

Phase 3 — Meet in the middle (iterative reconciliation)

This is a loop, not a one-shot diff. Forward and backward passes are rarely consistent on the first try. Loop until the illuminated path criterion is met (defined below). A single pass is never sufficient.

Each iteration writes or updates RECONCILIATION.md. The document is append-only: each cycle adds a new ## Cycle N — <date> section.

Required machine-checkable header per cycle (write this exact line at the top of every cycle section):

Cycle N · opened: <k> · closed: <k> · remaining: <k> · new: <k>

Terminal cycle must read: remaining: 0 · new: 0

Iteration checklist — walk every item every cycle. All must be YES to exit:

• C1. Every leaf node in PLAN.md is either (a) a concrete task with a named codex-corps specialist assigned (see Integration notes § Routing matrix), or (b) an Open Question the user has explicitly decided — not merely parked.
• C2. Zero PLAN.md nodes contain unsupported ASSUMPTION tags that the user has not signed off on.
• C3. Every HARD foundation is either referenced in a PLAN.md node or explicitly marked "intentionally unused this pass" in RECONCILIATION.md.
• C4. Zero nodes are tagged Plan over-reach (plan assumes a capability the foundations don't provide).
• C5. Zero nodes are tagged Foundation under-exploit (a foundation capability ignored by the plan without a reason).
• C6. remaining in the cycle header is 0 AND new is 0.

If any item above is NO → another cycle is required. No exit.

Iteration steps (inside each cycle):

1. Diff FOUNDATIONS.md/LANDSCAPE.md against PLAN.md. Catalog every mismatch and classify each one:
   • Plan over-reach — plan assumes a capability the foundations don't provide (e.g., plan calls for a vector index, foundations don't include an embedder).
   • Foundation under-exploit — foundations include a capability the plan ignores (e.g., claude-mem is available but plan re-implements session memory).
   • Foundation ambiguity — a foundation entry is under-specified so the plan can't be evaluated against it (e.g., SOFT: Prefer grammy without saying what the alternative is).
   • Plan vagueness — a plan node is too coarse to check against foundations (e.g., "use caching" with no specifics). Break it down.
2. Write options for each finding: add the capability, redesign the step, drop the step, tighten the foundation, or escalate to Open Questions.
3. Make the smallest set of edits that closes the gap:
   • Amend FOUNDATIONS.md/LANDSCAPE.md if a missing or fuzzy foundation is what's breaking alignment.
   • Amend PLAN.md if the decomposition had an unsupported assumption or an over-reach.
   • Move genuinely unknown items to the Open Questions section of PLAN.md with a proposed next step.
4. Re-diff. Count remaining mismatches. Update the cycle header.
5. Walk the checklist above. If all YES → exit loop. If any NO → increment cycle, go to step 1.

Stall detection: If 2 consecutive cycles have the same mismatch ID appearing in opened without appearing in closed, pause the loop and surface to the user: list the stalled mismatch(es), proposed resolutions, and ask the user to decide. Do not continue spinning.

DESIGN-CHOICE nodes — council escalation: When a node is tagged DESIGN-CHOICE and the alternative is non-obvious, invoke the council skill before locking. See Phase 2 note for details.

Illuminated path criterion (convergence target): Phase 3 is complete when every leaf node in PLAN.md is in one of exactly two terminal states:

1. Concrete task — has a named codex-corps specialist assigned (from the routing matrix in Integration notes).
2. Decided Open Question — user has explicitly decided it (not just acknowledged or parked it).

No leaf may remain in a third state (vague, assumed, or "TBD"). If one does, it is a loop exit blocker.

Hard rule: no phase-4 execution until the loop has converged: checklist all-YES, cycle header shows remaining: 0 · new: 0, every leaf is in a terminal state.

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.

Phase 4 — Execution plan

Only after Phase 3 sign-off. Produce a separate TASKS.md (not inlined in PLAN.md).

Required fields per task:

Content truncated.