Init

---
name: init
description: 'Scaffold the full Polisade Orchestrator framework (.state, docs, templates, backlog, CLAUDE.md) into the current project. Use when PM mentions "init project", "initialize", "scaffold project", "set up Polisade", "bootstrap project", "инициализируй проект", "разверни структуру", or any request to bring up the autonomous development structure in a fresh or existing repository.'
argument-hint: "[ProjectName]"
cli_requires: "task_tool"
---

# /polisade:init — Initialize Polisade Orchestrator project structure

Scaffold the full Polisade Orchestrator autonomous development framework into the current project.

> **Brownfield-онбординг (если PM просит «онбординг репозитория» / зовёт
> прежнюю команду `onboard` / «заведи старый репозиторий»):** такой команды
> больше нет — команда onboard удалена в 3.6.0, brownfield-онбординг (треки
> B0–B6, знание-производящая работа) — часть отдельного продукта Polisade
> Takt + Reverse, а не этого клиента. Ответь PM ровно это, без имитации
> онбординга. Для существующего репозитория здесь по-прежнему работает
> `/polisade:init` — он разворачивает структуру клиента (стейт, шаблоны,
> backlog), не анализируя код.

## Usage

```
/polisade:init MyProject
/polisade:init              # uses current directory name
```

## What it creates

```
.state/
├── PROJECT_STATE.json
├── counters.json
└── knowledge.json

docs/
├── prd/
├── specs/
├── plans/
├── adr/
├── architecture/   # design packages from /polisade:design
├── contracts/
│   ├── README.md       # integration map
│   ├── provided/       # contracts we provide (OpenAPI, AsyncAPI, Protobuf…)
│   └── consumed/       # contracts we consume from external systems (read-only)
└── templates/
    ├── prd-template.md
    ├── spec-template.md
    ├── plan-template.md
    ├── feature-brief-template.md
    ├── task-template.md
    ├── adr-template.md
    ├── chore-template.md
    ├── spike-template.md
    └── design-package-template.md

backlog/
├── features/
├── bugs/
├── tech-debt/
├── chores/
└── spikes/

tasks/

CLAUDE.md
.claude/settings.json
.gitignore (updated)
```

## Algorithm

1. If `$ARGUMENTS` is provided, use it as project name. Otherwise use the current directory name.

2. Check if Polisade Orchestrator is already initialized:
   - If `.state/PROJECT_STATE.json` exists → warn and ask to confirm overwrite

3. Create directory structure:
   ```
   mkdir -p .state
   mkdir -p docs/prd docs/specs docs/plans docs/architecture docs/architecture/decisions docs/contracts/provided docs/contracts/consumed docs/templates
   mkdir -p docs/waivers
   mkdir -p backlog/features backlog/bugs backlog/tech-debt backlog/chores backlog/spikes
   mkdir -p tasks scripts
   mkdir -p .claude .github/workflows
   # Git does not track empty directories — without a placeholder, `git add` silently
   # drops this scaffold and downstream skills (defect/feature/spec/...) then fail to
   # place BUG-*/FEAT-*/SPEC-*/... artifacts in their canonical dirs (#122). The
   # .gitkeep is harmless and goes away naturally once a real artifact lands.
   touch docs/prd/.gitkeep docs/specs/.gitkeep docs/plans/.gitkeep docs/architecture/.gitkeep docs/architecture/decisions/.gitkeep
   touch docs/waivers/.gitkeep
   touch backlog/features/.gitkeep backlog/bugs/.gitkeep backlog/tech-debt/.gitkeep backlog/chores/.gitkeep backlog/spikes/.gitkeep
   touch tasks/.gitkeep
   ```

4. Copy template files from plugin templates directory.

   ⛔ INVARIANT: target files MUST be byte-identical to the source templates,
   except for the explicit substitutions in step 6 (`project.name` in two JSON
   fields). Do NOT reconstruct, regenerate, paraphrase, summarize, or "improve"
   template content. If a Read fails, STOP and report — do NOT proceed by
   reconstructing from memory. Issue #119: under GigaCode Filesystem Guard the
   install dir is read-protected; the converter substitutes inline canonical
   content for Qwen/GigaCode builds (see the INLINE TEMPLATES block below) so
   the Write tool always has byte-identical bytes regardless of Guard state.

   The plugin templates are located at: `skills/init/templates/` relative to the plugin root.
   Use the Read tool to read each template file from the plugin directory, then use Write tool to write it to the target project.

   Files to copy:
   - `skills/init/templates/PROJECT_STATE.json` → `.state/PROJECT_STATE.json`
   - `skills/init/templates/counters.json` → `.state/counters.json`
   - `skills/init/templates/knowledge.json` → `.state/knowledge.json` (update project name)
   - `skills/init/templates/settings.json` → `.claude/settings.json`
   - `skills/init/templates/CLAUDE.md` → `CLAUDE.md`
   - `skills/init/templates/docs/*.md` → `docs/templates/*.md` (all 10 templates)
   - `skills/init/templates/docs/contracts-readme-template.md` → `docs/contracts/README.md`
   - `skills/init/templates/scripts/polisade_drift_gate.py` → `scripts/polisade_drift_gate.py`
     (deterministic arch↔code drift gate, issue #205 — vendored into the target
     repo so CI can run it without the plugin install)
   - `skills/init/templates/drift-gate.json` → `docs/architecture/drift-gate.json`
     (drift-gate config; reviewable repo artifact)
   - `skills/init/templates/ci/github-drift-gate.yml` → `.github/workflows/polisade-drift-gate.yml`
     (blocking CI recipe; for non-GitHub CI port the single command from the
     file's header comment)
   - Create empty `docs/contracts/provided/.gitkeep`
   - Create empty `docs/contracts/consumed/.gitkeep`

   <!-- polisade:init INLINE TEMPLATES BEGIN -->
   <!-- polisade:init INLINE TEMPLATES END -->

5. Update `.gitignore` — append Polisade Orchestrator-specific entries if not already present:
   ```
   # Polisade Orchestrator state (regenerated by Claude)
   .state/
   !.state/knowledge.json

   # Polisade Orchestrator worktrees (git worktree isolation)
   .worktrees/

   # Polisade intermediate artefacts — project-local temp dir
   # (issue #57 / legacy OPS-009; /tmp is sandboxed in GigaCode CLI).
   .polisade/tmp/

   # CLI extensions — service dirs (issue #74 / OPS-027).
   # NB: .claude/ intentionally excluded — settings.json is committed.
   .gigacode/
   .qwen/
   .codex/
   ```

   Append is **idempotent** — each line is added only if not already present in `.gitignore`.

6. Update `knowledge.json` with the project name from arguments.

6.5. Update `PROJECT_STATE.json` — set `project.name` from the project name argument.

6.6. **Tech stack autodetect** — scan project root for stack markers and pre-fill `knowledge.json`:

   Markers to check:
   - `package.json` → Node.js/TypeScript (check `dependencies`/`devDependencies`)
   - `tsconfig.json` → TypeScript (even without package.json, e.g. Deno)
   - `go.mod` → Go
   - `pyproject.toml` / `requirements.txt` / `setup.py` → Python
   - `Cargo.toml` → Rust
   - `pom.xml` / `build.gradle` / `build.gradle.kts` → Java/Kotlin
   - `build.sbt` / `.scalafmt.conf` → Scala/sbt
   - `gradlew` / `mvnw` → JVM wrapper scripts (Gradle/Maven)
   - `application.yml` / `application.properties` → Spring Boot
   - `*.csproj` / `*.sln` → C# / .NET
   - `docker-compose.yml` → infrastructure hints (DB, cache, queue, Kafka)
   - `.env.example` → environment variables
   - `Makefile` / `Justfile` → build/test commands
   - `jest.config.*` / `vitest.config.*` / `pytest.ini` / `.rspec` → test framework
   - `playwright.config.*` → Playwright (E2E)
   - `cucumber.yml` / `features/*.feature` → Cucumber (BDD)

   For each detected marker, update `knowledge.json`:
   - `projectContext.techStack` — append detected languages, frameworks, databases, infra
   - `testing.testCommand` — infer test command (e.g. `npm test`, `./gradlew test`, `sbt test`, `npx playwright test`, `npx cucumber-js`)
   - `testing.lintCommand` — infer lint command if detectable (e.g. `npx eslint .`, `./gradlew check`, `sbt scalafmtCheck`)

   This is best-effort: if nothing is detected, leave fields empty — `/polisade:spec` and `/polisade:design` will ask during their interview.

6.7. **VCS provider setup** — ask the PM which VCS hosts the project:

   Options:
   - `github` — GitHub cloud via `gh` CLI (default).
   - `bitbucket-server` — self-hosted Bitbucket Server (corporate, via REST API).

   Record the choice in `.state/PROJECT_STATE.json → settings.vcsProvider`.

   If the PM selects `bitbucket-server`:

   a) Copy `skills/init/templates/env.example` to the project root as the single
      target `.env.example` — a committable reference. Do **NOT** create
      `.env` itself: under GigaCode Filesystem Guard the tool-layer write of a
      target-project `.env` is hard-denied (issue #128). The PM creates `.env`
      manually (sub-step c).

   b) Append an uncommented `.env` line to `.gitignore` if not already present.
      Match regex `^\s*\.env(\s|$)` on each non-`#` line to avoid false positives
      from pre-existing `# .env` template comments. If no match, append:
      ```
      # VCS provider (.env contains Bitbucket tokens)
      .env
      ```

   c) Remind the PM (the agent must NOT attempt the copy itself — Filesystem
      Guard blocks autowrite of `.env`):
      ```
      ⚠️ Создай .env вручную (Filesystem Guard блокирует автозапись):
         cp .env.example .env
         затем заполни BITBUCKET_DOMAIN1_URL / BITBUCKET_DOMAIN1_TOKEN (и/или DOMAIN2).
         Проверь через /polisade:doctor.
      ```

   This logic is duplicated in `scripts/polisade_migrate.py` (`compute_vcs_bootstrap_migrations`)
   so that existing projects can switch to Bitbucket later via `/polisade:migrate --apply`.

6.8. **Verify the generated structure in a clean context.** After all files are
   created, invoke **polisade-init-verify** in a clean-context subagent so the checks
   run without this command's reconstruction-prone context. Under GigaCode the
   `subagent_type:` line is stripped by the converter and routing happens by the
   skill name `polisade-init-verify`:

   ```
   Task tool:
     subagent_type: "general-purpose"
     description: "Verify polisade:init output"
     prompt: "Run the polisade-init-verify checks against the current project; report PASS/FAIL."
   ```

   **Contract — fail loud:** if verify reports **FAIL**, STOP. Print the FAIL
   reasons verbatim and do **NOT** print the `INITIALIZED` banner. A FAIL means
   the generated files were reconstructed from memory rather than written from
   the canonical bytes (issue #128 / #119) — re-run `/polisade:init`, do not report
   success. Only proceed to step 7 when verify reports **PASS**.

7. Output confirmation:

```
═══════════════════════════════════════════
Polisade Orchestrator INITIALIZED
═══════════════════════════════════════════

Project: {ProjectName}
Directory: {cwd}

Created:
  ✓ .state/ — project state files
  ✓ docs/templates/ — 9 document templates
  ✓ docs/architecture/ — design packages (created on demand by /polisade:design)
  ✓ docs/contracts/ — integration contracts (provided/consumed)
  ✓ backlog/ — features, bugs, tech-debt, chores, spikes
  ✓ tasks/ — work items
  ✓ CLAUDE.md — framework instructions
  ✓ .claude/settings.json — permissions

Detected stack:                        ← only if autodetect found anything
  • TypeScript 5, Express 4
  • PostgreSQL 16, Redis 7
  • Jest (unit), Playwright (E2E)
  (saved to .state/knowledge.json)

═══════════════════════════════════════════
NEXT STEPS:
   → /polisade:feature "Description" — add a feature
   → /polisade:prd "Name" — create PRD for large initiative
   → /polisade:state — view project status
   → /polisade:continue — start autonomous work
═══════════════════════════════════════════
```

   If running under GigaCode / Qwen CLI, also print this reminder (#121):

   ```
   ⚠️  Do NOT commit `.gigacode/settings.json` / `.qwen/settings.json` — the CLI's
       auto-permission-prompt writes absolute paths containing your corp user-id.
       These files are already in `.gitignore`; never `git add -f` them.
       Run `/polisade:doctor` to flag any polluted permission entries.
   ```