AirCoding/AirPlan/docs/spec/AirPlan-ParaV2/init_project_airplan.ps1

param(
    [string]$ProjectRoot = ".",
    [switch]$Force
)

$ErrorActionPreference = "Stop"

$resolvedProjectRoot = (Resolve-Path $ProjectRoot).Path
$airPlanRoot = Join-Path $resolvedProjectRoot "AirPlan"

function Ensure-Directory {
    param([Parameter(Mandatory = $true)][string]$Path)
    New-Item -ItemType Directory -Path $Path -Force | Out-Null
}

function Write-TextFile {
    param(
        [Parameter(Mandatory = $true)][string]$Path,
        [Parameter(Mandatory = $true)][string]$Content
    )

    if ((Test-Path -LiteralPath $Path) -and (-not $Force)) {
        Write-Output ("skipped=" + $Path)
        return
    }

    $parent = Split-Path -Parent $Path
    if ($parent) {
        Ensure-Directory -Path $parent
    }
    [System.IO.File]::WriteAllText($Path, $Content.TrimStart("`n") + "`n", [System.Text.UTF8Encoding]::new($false))
    Write-Output ("written=" + $Path)
}

$rootAgents = @'
# AGENTS.md

- Canonical workflow context for this repository lives in `AirPlan/AGENTS.md`.
- Always load `AirPlan/AGENTS.md` first for project instructions, workflow rules, plan/todo state, ADR/C4 context, and current Air sync blocks.
- Treat `AirPlan/plan.md`, `AirPlan/todo.md`, and `AirPlan/docs/` as the authoritative workflow documents.
- Treat `AirPlan/state/` as the authoritative plugin and runtime state root.
- This root file is only a bootstrap shim; keep real workflow context maintained inside `AirPlan/AGENTS.md`.
'@

$projectAgents = @'
# AGENTS.md

## Workflow Root

- This project uses `AirPlan/` as the workflow root.
- Keep planning, execution state, ADR, C4, validation, debug, and plugin runtime data under `AirPlan/`.
- The repo-root `AGENTS.md` only bootstraps into this file.

<!-- AIRARC:BEGIN -->
## AirArc Workflow

1. Use `AirPlan/AGENTS.md` as the canonical project context entry point.
2. Load and maintain:
   - `AirPlan/docs/analysis/requirements.md`
   - `AirPlan/docs/architecture/solution-architecture.md`
   - `AirPlan/docs/architecture/c4/module.md`
   - `AirPlan/docs/architecture/adr/`
3. Produce or refine `AirPlan/plan.md` and `AirPlan/todo.md`.
4. Keep plans optimized for lower-cost follow-up sessions, including scope, validation, file targets, and parallelization boundaries.
<!-- AIRARC:END -->

<!-- AIRENG:BEGIN -->
## AirEng Workflow

1. Use `/aireng` as the scheduler for confirmed execution.
2. Prefer `AirPlan/state/airarc/reviews/execution-plan.json`, then `AirPlan/state/airarc/reviews/parallel-review.json`, before falling back to local `AirPlan/todo.md`.
3. Dispatch isolated `/airdo` subagents with bounded concurrency.
4. Keep `AirPlan/todo.md`, `AirPlan/plan.md`, `AirPlan/AGENTS.md`, ADR, and C4 docs synchronized during dispatch and merge.
5. AirEng owns global debug, XDB, repair, and document convergence.
<!-- AIRENG:END -->

<!-- AIRDO:BEGIN -->
## AirDo Workflow

1. Use `/airdo` for one narrow task slice from `AirPlan/todo.md`.
2. Before editing, load:
   - `AirPlan/AGENTS.md`
   - `AirPlan/docs/architecture/adr/`
   - `AirPlan/docs/architecture/c4/module.md`
   - `AirPlan/plan.md`
   - `AirPlan/todo.md`
3. Keep task-local progress resumable in `AirPlan/state/airdo/`.
4. When AirEng owns orchestration, return shared document changes through `documentUpdates`.
5. Route GUI work through AirXDB, debugging through AirDbg, network evidence through AirNDB, and static analysis through AirSDB when needed.
<!-- AIRDO:END -->
'@

$planMd = @'
# Implementation Plan

## Read First
1. `AirPlan/AGENTS.md`
2. `AirPlan/docs/analysis/requirements.md`
3. `AirPlan/docs/architecture/solution-architecture.md`
4. `AirPlan/docs/architecture/c4/module.md`
5. `AirPlan/docs/architecture/adr/`
6. `AirPlan/todo.md`

## Goal
- Replace this section with the concrete product or project goal.

## Constraints
- Record technical, organizational, legal, hardware, or platform constraints here.

## Phases
- Add implementation phases once AirArc planning is complete.

## Validation Strategy
- Record build, test, debug, GUI, network, and static-analysis validation commands here.
'@

$todoMd = @'
# TODO

Status values: TODO / DOING / DONE / BLOCKED

| ID | Status | Module | Task | Files/Dirs | Done When | Validation | Static Analysis | ADR/C4 Update |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| T-001 | TODO | Planning | Replace with the first confirmed execution task | `AirPlan/plan.md`, `AirPlan/docs/` | Acceptance criteria are explicit and testable | Record the exact validation command | Record the static-analysis plan or why it is not applicable | Record required ADR or C4 updates |

## Quality Gates
- Run the validation command listed in `AirPlan/plan.md` before marking a task `DONE`.
- Keep ADR and C4 docs synchronized whenever architecture, module boundaries, dependencies, or ownership change.
- Record skipped validation, residual risk, and follow-up work explicitly.
'@

$requirementsMd = @'
# Requirements

## Product Intent
- Replace with the user-visible outcome this repository should deliver.

## Functional Requirements
- Replace with numbered or grouped functional requirements.

## Constraints
- Replace with non-functional constraints, environmental limits, or safety rules.

## Acceptance Notes
- Replace with the most important acceptance criteria and evidence rules.
'@

$solutionArchitectureMd = @'
# Solution Architecture

## Overview
- Replace with the top-level architecture summary.

## Major Components
- Replace with the main containers and their responsibilities.

## Data And Control Flow
- Replace with the major interaction paths between components.

## Key Risks
- Replace with the architecture risks, unknowns, and open decisions.
'@

$c4ModuleMd = @'
# C4 Module

## System Context
- Replace with the project purpose and external actors or systems.

## Containers
- Replace with the main runtime or repository containers.

## Modules

| Module | Responsibility | Public Interfaces | Dependencies | Data Ownership | Quality Notes |
| --- | --- | --- | --- | --- | --- |
| `replace_me` | Replace with the first real module | Replace with interfaces | Replace with dependencies | Replace with owned data | Replace with testing or quality notes |
'@

$adrMd = @'
# ADR-0001: Use AirPlan As The Workflow Root

- Status: Accepted
- Date: YYYY-MM-DD

## Context
This project needs a durable workflow root for planning, execution state, architecture context, validation evidence, and resumable AI sessions.

## Decision
Store project workflow artifacts under `AirPlan/`, use the repo-root `AGENTS.md` only as a bootstrap shim, and let `aireng` plus `airdo` maintain plan, todo, ADR, and C4 context there.

## Consequences
- Planning and execution context stay resumable across sessions.
- Global workflow docs live in one predictable location.
- Plugin runtime state does not clutter the main project tree.
'@

$debugLogMd = @'
# Debug Log

- Add reproducible bug investigations, root-cause notes, and validation outcomes here.
'@

$guiDebugLogMd = @'
# GUI Debug Log

- Add screenshots, GUI observations, Midscene evidence, and visual acceptance notes here.
'@

$networkLogMd = @'
# AirNDB Log

- Add packet-capture commands, pcap paths, network observations, and conclusions here.
'@

$staticAnalysisMd = @'
# Static Analysis

- Add cppcheck or other static-analysis summaries, report paths, and residual risks here.
'@

$validationReadme = @'
# Validation Artifacts

- Save build logs, flash logs, test logs, screenshots, and validation summaries under this directory.
'@

$artifactsReadme = @'
# Artifact Output

- Save generated evidence files in this directory.
'@

Ensure-Directory -Path $airPlanRoot
Ensure-Directory -Path (Join-Path $airPlanRoot "docs\analysis")
Ensure-Directory -Path (Join-Path $airPlanRoot "docs\architecture\adr")
Ensure-Directory -Path (Join-Path $airPlanRoot "docs\architecture\c4")
Ensure-Directory -Path (Join-Path $airPlanRoot "docs\debug\airxdb-artifacts")
Ensure-Directory -Path (Join-Path $airPlanRoot "docs\network\airndb-captures")
Ensure-Directory -Path (Join-Path $airPlanRoot "docs\validation\logs")
Ensure-Directory -Path (Join-Path $airPlanRoot "state")

Write-TextFile -Path (Join-Path $resolvedProjectRoot "AGENTS.md") -Content $rootAgents
Write-TextFile -Path (Join-Path $airPlanRoot "AGENTS.md") -Content $projectAgents
Write-TextFile -Path (Join-Path $airPlanRoot "plan.md") -Content $planMd
Write-TextFile -Path (Join-Path $airPlanRoot "todo.md") -Content $todoMd
Write-TextFile -Path (Join-Path $airPlanRoot "docs\analysis\requirements.md") -Content $requirementsMd
Write-TextFile -Path (Join-Path $airPlanRoot "docs\architecture\solution-architecture.md") -Content $solutionArchitectureMd
Write-TextFile -Path (Join-Path $airPlanRoot "docs\architecture\c4\module.md") -Content $c4ModuleMd
Write-TextFile -Path (Join-Path $airPlanRoot "docs\architecture\adr\ADR-0001-use-airplan-as-the-workflow-root.md") -Content $adrMd
Write-TextFile -Path (Join-Path $airPlanRoot "docs\debug\debug-log.md") -Content $debugLogMd
Write-TextFile -Path (Join-Path $airPlanRoot "docs\debug\gui-debug-log.md") -Content $guiDebugLogMd
Write-TextFile -Path (Join-Path $airPlanRoot "docs\debug\airxdb-artifacts\README.md") -Content $artifactsReadme
Write-TextFile -Path (Join-Path $airPlanRoot "docs\network\airndb-log.md") -Content $networkLogMd
Write-TextFile -Path (Join-Path $airPlanRoot "docs\network\airndb-captures\README.md") -Content $artifactsReadme
Write-TextFile -Path (Join-Path $airPlanRoot "docs\validation\README.md") -Content $validationReadme
Write-TextFile -Path (Join-Path $airPlanRoot "docs\validation\logs\README.md") -Content $artifactsReadme
Write-TextFile -Path (Join-Path $airPlanRoot "docs\staticanalysis.md") -Content $staticAnalysisMd

Write-Output ("airplan_project_init=completed")
Write-Output ("project_root=" + $resolvedProjectRoot)
Write-Output ("airplan_root=" + $airPlanRoot)