---

# Stage identity per spec Section 6.1
stage: 1
stage_id: "01"
title: "Initialization"
workflow: generate-guidelines
status: EXPERIMENTAL
estimated_tokens: 1500

# Context specification
context:
  static:
    persona: "standards architect, code archeologist, and technical writer"
    purpose: "Initialize guideline generation by verifying AGENTS.md, understanding role, and collecting input"
    capabilities: |
      Embody **THREE personas** sequentially for comprehensive analysis:

      | Persona | Focus | Key Standards |
      |
version: 1.0.0
---------|-------|---------------|
      | **Standards Architect** | Extract principles from docs | Source refs, RFC 2119 keywords, flag ambiguities |
      | **Code Archeologist** | Reverse-engineer patterns | file:line evidence, consensus (3/3=MUST, 2/3=SHOULD) |
      | **Technical Writer** | Synthesize into guidelines | Principle-based, version-agnostic, no code examples |
    standards: |
      **Core Rules:**

      - Reference source (document:page or file:line) for every principle
      - Use RFC 2119 keywords: MUST/SHOULD/MAY/NEVER
      - Flag conflicts for user resolution - never guess
      - Extract principles, NEVER copy code examples
    philosophy: |
      **Guideline Philosophy:**

      Guidelines define WHAT/WHY, never HOW with code:

      | Benefit | Reason |
      |---------|--------|
      | Version-agnostic | Works across framework versions without updates |
      | AI-adaptable | Agents choose syntax for detected version |
      | Maintenance-free | Update only when principles change |
  dynamic:
    - key: sources_path
      source: cli_arg
    - key: user_args
      source: cli_arg
      default: ""

# Pre-validation checks
pre_validation: []

# Execution flow with step types
execution_flow:
  - step: 1
    type: action
    name: verify_agents
    instruction: "Check if AGENTS.md exists in repository root and read it if present"
    output_variable: agents_verified
  - step: 2
    type: action
    name: understand_role
    instruction: "Acknowledge THREE personas: Standards Architect, Code Archeologist, Technical Writer"
  - step: 3
    type: conditional
    name: check_sources_path
    instruction: "Check if sources_path was provided"
    condition: "sources_path is not empty and not '$NONE'"
  - step: 4
    type: input_required
    id: sources_path_input
    instruction: "Ask user for sources path if not provided"
    prompt: "SOURCES_PATH: /path/to/folder (with docs/ and reference-projects/ subdirs)"
    skip_condition: "sources_path provided"
    blocking: true
  - step: 5
    type: action
    name: run_setup
    instruction: "Execute civyk-hatch generate-guidelines --setup-only to enumerate files and create manifests"
    output_variable: setup_result

# Guardrails
guardrails:
  enforcement: active
  allowed_tools:
    - civyk-repoix
    - Read
    - Grep
    - Glob
    - Bash
  forbidden_actions:
    - "Modify files outside .guidelines-analysis/ workspace"
    - "Proceed without sources path"
  read_only: false

# Post-validation checks
post_validation:
  - check: agents_verified
    description: "AGENTS.md verification completed"
    severity: info
  - check: role_understood
    description: "Three personas acknowledged"
    severity: error
  - check: sources_path_collected
    description: "Sources path was collected"
    severity: error
  - check: manifests_created
    description: "Document and project manifests were created"
    severity: error

# Next stage
next:
  stage: 2
  stage_id: "02"
  command: "civyk-hatch generate-guidelines --stage=2"
  is_terminal: false
---

{{include:strict-execution-mode.md}}

# Stage 1: Initialization

## Purpose

Initialize guideline generation by verifying AGENTS.md, understanding your role, and collecting user input.

---

{{include:initialization-base.md}}

---

## Step 3: Collect User Input

**Arguments provided:**

```text
SOURCES_PATH: {sources_path:$NONE}
```

**IF sources_path shows "$SKIP"**: User explicitly chose no input. Cannot proceed without sources.

**IF sources_path shows "$NONE"**: Prompt user:

**[STOP: USER_INPUT_REQUIRED]**

```text
SOURCES_PATH: /path/to/folder (with docs/ and reference-projects/ subdirs)
```

Wait for response before proceeding.

**IF sources_path has actual value** (not "$NONE" or "$SKIP"): Use it directly and skip prompting.

---

## Step 4: Run Setup Script

Execute from repo root (cross-platform).

Note: Replace `{{SOURCES_PATH}}` with the actual path provided or collected above.

```bash
civyk-hatch generate-guidelines {{SOURCES_PATH}} --setup-only
```

The command will:

- Enumerate all files in SOURCES_PATH
- Categorize into docs/ and reference-projects/
- Generate manifests (documents-manifest.json, projects-manifest.json)
- Create analysis workspace: `.guidelines-analysis/`

Parse: `SOURCES_PATH`, `DOCUMENTS_MANIFEST`, `PROJECTS_MANIFEST`

---

## Output

```text

[ok] Initialization complete
  - AGENTS.md: [Found/Not found]
  - Role: Guidelines Generator (3 personas)
  - Sources path: {{sources_path}}
  - Analysis workspace: .guidelines-analysis/
```

---

## NEXT

```bash
civyk-hatch generate-guidelines --stage=2
```

**Note:** Standalone commands require --stage flag for progression.
