Init Architect

Purpose

Run once after installing skills (and rerun when architecture drifts) to create or refresh architecture-folder artifacts used by architect-agent . Also supports scoped updates when invoked from pr-review-agent for architecture-impacting PR changes.

Runtime Configuration

• Read /orchestra-config.json from the repository root before starting.

• If /orchestra-config.json is missing, create it at repository root with:

• { "issue_tracker": "linear" }

• Read issue_tracker and use it for any generated tracker-facing instructions.

• Allowed issue_tracker values: linear , jira .

• For tracker comments in workflow-scoped mode, include: Skill-Version: init-architect@2.0.0 .

When to Invoke

• Immediately after skill installation, before running architect-agent .

• When architecture artifacts are stale after major system changes.

• When pr-review-agent flags architecture-impacting changes and provides scoped PR context.

Required Inputs

• Repository root path.

• Invocation mode:

• full (default): repository analysis and full architecture refresh.

• scoped : targeted update using PR-derived scope.

• For scoped mode:

• parent issue ID.

• PR identifier/link.

• changed files list.

• concise diff summary.

• matched architecture-impact cases.

• suggested architecture sections.

• Optional existing /architecture/architecture.md .

• Optional existing /architecture/docs/*.md .

• Optional existing skills/init-architect/ARCHITECTURE.md template.

• Most recent prior handoff comment in <!-- OPEN-ORCHESTRA-HANDOFF --> format when running in workflow-scoped mode.

Outputs

• /orchestra-config.json in repository root (created only if missing).

• /architecture/architecture.md populated as the architecture index.

• /architecture/docs/*.md populated for complex domains.

• In scoped mode: only impacted sections/documents are updated; unaffected sections remain unchanged.

• Optional targeted updates to skills/architect-agent/SKILL.md reference tables so runtime guidance matches generated docs.

• For workflow-scoped mode, a handoff comment wrapped exactly as:

{ "execution_trace": "Execution-Trace:\nActions:\n1. <action>\n2. <action>\nDecisions:\n- <architecture update decision + reason>\nReferences:\n- <changed files or architecture docs>\nAssumptions:\n- <assumption>\nOpen-Questions: none|<question list>\nSkill-Version: init-architect@2.0.0", "handoff_summary": { "from_skill": "init-architect", "to_skill": "architect-agent|pr-review-agent", "status": "ready|blocked|completed", "delta": ["<what changed in architecture artifacts>"], "key_decisions": [{"decision": "<decision>", "reason": "<reason>"}], "relevant_artifacts": [ { "artifact": "architecture-index-or-doc", "hash": "sha256:<hash>", "last_modified": "<ISO-8601>", "summary": "<updated sections and rationale>" } ], "open_blockers": [{"blocker": "<text>", "owner": "<owner>", "next_action": "<action>"}], "next_guidance": { "need_full": ["architecture/architecture.md"], "focus": ["<sections downstream agents must re-check>"] } } }

• handoff_summary must be <= 600 tokens.

Context Gathering Order (Strict)

• Locate the most recent comment containing <!-- OPEN-ORCHESTRA-HANDOFF --> from the previous skill.

• Parse the JSON inside it. This is your primary context.

• Look at its relevant_artifacts list and hashes.

• Declare exactly which artifacts you need via need_full .

• Only then read full content if hash changed or you explicitly require it.

• In non-workflow bootstrap mode with no prior handoff, continue with repository artifacts only.

Procedure

• Ensure /orchestra-config.json exists and has key issue_tracker .

• Execute the strict context gathering order above when in workflow-scoped mode.

• Ensure scaffold exists:

• skills/init-architect/ARCHITECTURE.md .

• Ensure generated artifact paths exist:

• /architecture/architecture.md .

• /architecture/docs/ .

• If architecture content currently lives under /ARCHITECTURE.md or /docs/ , migrate relevant content into /architecture/ and stop updating legacy root-level copies.

• Determine mode:

• If scoped payload is present, run scoped mode.

• Otherwise run full mode.

• In full mode, analyze repository structure (do not read every source file):

• stack, entry points, boundaries, data layer, integrations, auth, sensitive areas, conventions.

• In full mode, write/update /architecture/architecture.md as a concise index:

• system overview.

• component map.

• sensitive areas.

• conventions.

• reference docs table.

• In full mode, create/update /architecture/docs/*.md only for domains that need detail beyond the index.

• In scoped mode, use provided PR scope first and update only impacted architecture artifacts:

• map changed files and matched cases to existing sections in /architecture/architecture.md .

• update only relevant sections in /architecture/architecture.md .

• update or create only the necessary /architecture/docs/*.md files tied to those sections.

• keep unrelated sections/documents untouched.

• In scoped mode, preserve current architecture structure and terminology unless the PR clearly introduces a new boundary or domain.

• Keep index shallow; move depth to domain docs.

• If generated docs change domain/sensitive-area mapping, update relevant sections in skills/architect-agent/SKILL.md .

• In workflow-scoped mode, post handoff JSON with status: completed or status: blocked .

Guardrails

• This skill owns architecture artifact generation; architect-agent must not regenerate architecture docs.

• Do not overwrite skills/init-architect/ARCHITECTURE.md template files.

• Keep generated architecture artifacts under /architecture/ (/architecture/architecture.md , /architecture/docs/*.md ).

• Prefer clarity over coverage; do not scan the full codebase unnecessarily.

• In scoped mode, do not perform a full repository rescan unless scoped context is insufficient.

• In scoped mode, prioritize consistency with existing architecture docs and produce minimal diffs.

Handoff

Primary consumers: architect-agent , pr-review-agent (scoped invocation).