setup-project

name	setup-project
description	Reconcile a repository with the live Knowledge Bank project conventions.
disable-model-invocation	true

Setup Project

Reconcile the current repository with the conventions that are canonical in the live Knowledge Bank. Add missing applicable conventions, update stale implementations, preserve valid project-local extensions, and leave the repository idempotently aligned.

This internal module is canonical here. Its repository-setup procedure and seed documents are bundled under resources/; do not read a workspace-installed copy as source. The Knowledge Bank is a System dependency reached through the independently installed /lookup public contract. Do not cache its conventions in this skill or copy the master convention page into project documentation.

1. Read the live conventions

Read the available /lookup skill completely and use its context branch to resolve the canonical shared project-convention owner. Treat build as a search hint, not proof of the current owner or content.

Fetch the complete shared-conventions section, the current project's Knowledge Bank owner when one exists, and only the relations needed to identify project-local rules or explicit exceptions. Read Blueprint only when the live convention names it as the reference implementation.

Stop before editing when /lookup is unavailable, the live Knowledge Bank is unavailable, the canonical owner is ambiguous, or a relevant project-local rule cannot be verified. Report the scope as unverified; never fall back to a bundled convention snapshot.

Completion criterion: every entry in the complete fetched shared-conventions section, plus every applicable project-owned rule or exception, has current evidence and a clear owner.

2. Explore the repository

Read resources/repository-setup.md completely. Follow its tracker, label, domain-doc, template, and interview behavior, but include all proposed writes in this skill's unified confirmation.

When the live convention selects a canonical root instruction file, that selection overrides the bundled procedure's root-file choice. Apply its templates and content rules in the live convention's selected file, and materialize any compatibility file exactly as the live convention requires.

Inspect the repository before proposing changes:

• root and nested instruction files;
• existing docs/agents/, domain docs, ADRs, README, trust files, CI, dependency automation, release configuration, and canonical validation command;
• Git remotes, repository class signals, package and runtime metadata, and current working-tree changes;
• live remote settings when the applicable convention governs them and authenticated access exists.

Classify the repository using the live convention. Prefer the linked project owner's explicit class or local rules over inference. Ask only when a material ambiguity would change the reconciliation.

Preserve unrelated work and unique project guidance. A project-local rule may extend the shared convention. Treat a contradiction as stale only when it is not an explicit, current exception.

Completion criterion: every listed repository surface is inspected or recorded as absent or unavailable, the repository class has fetched evidence or an explicit inference, existing work is accounted for, and the root instruction targets are resolved from the live convention.

3. Complete the setup interview

Run the bundled setup questions in their documented order. Add this question as a separate setup choice:

Do you want to link this project to the Personal Mastery Program as an optional Project Lab? Recommended: no, unless you want a PMP Learning Cycle to use this project.

On yes, make the live Knowledge Bank's conditional PMP block applicable. On no, do not add PMP instructions or require a Learning Cycle link. If PMP instructions already exist, mark them as stale and propose their removal; do not remove them before the unified confirmation.

Ask this question on every setup or reconciliation run so the user can opt in or out deliberately. The question and recommendation belong only to this skill; never write them into the Knowledge Bank convention or the project.

Completion criterion: every applicable bundled setup choice and an explicit PMP yes or no are recorded for the drift plan.

4. Build one drift plan and confirm it

Compare the repository with every applicable live convention. Classify each item as:

• aligned: no change;
• missing: add the materialized convention;
• stale: update or remove the conflicting implementation;
• local exception: preserve the explicit project-owned divergence;
• not applicable: explain briefly;
• blocked: name the missing evidence, authority, or capability.

Show the repository class, setup choices, PMP choice, drift map, exact local files, and any remote settings that would change. Make no local or remote write before the user confirms the unified plan.

Do not treat a technology default as permission for an unplanned architecture migration. Put high-cost technology or architecture contradictions behind an explicit decision and domain-reconnaissance when its trigger applies.

Completion criterion: every entry in the fetched shared-conventions section and every applicable project-owned rule has exactly one drift classification, every proposed write is shown, and the user has confirmed that exact plan.

5. Reconcile the project

Immediately before writing, re-fetch the canonical convention section and any project-local exception that determined the plan. Drift invalidates confirmation; refresh the plan and confirm again.

After confirmation:

1. Apply the bundled repository-setup writes using its templates and content rules, with root instruction destinations selected by the current live convention.
2. Add every missing applicable materialized convention.
3. Update every confirmed stale implementation.
4. Preserve aligned content, scoped instruction files, local exceptions, and unique user guidance.
5. If PMP was accepted, copy the exact current conditional block from the live Knowledge Bank into root AGENTS.md once. If declined, leave it absent or perform only the confirmed removal.
6. Apply confirmed remote-setting changes only when authenticated access exists. Return exact commands and mark them blocked when the write is unavailable.

Implement conventions through the repository's real structure. Do not add a local document that restates the master Knowledge Bank page.

Completion criterion: every confirmed local or remote change is applied or marked blocked with an exact follow-up, and the working tree contains no unconfirmed delta from this run.

6. Validate and report

Recompute the drift map against a fresh read of the live convention. Verify the configured docs/agents/ files, instruction ownership, remote settings that changed, and every applicable convention in scope.

Inspect the final diff, run git diff --check when Git is available, and run the repository's canonical validation command when documented. Report the setup changes, Knowledge Bank convention changes, preserved local exceptions, aligned and not-applicable items, blockers, and validation results.

Completion criterion: all applicable items are aligned or an explicit local exception, blocked items are visible, no unrelated content changed, and re-running the skill would produce no unconfirmed delta.