00-meta-initialization

name	00-meta-initialization
description	Use when starting project documentation to detect project type, select Waterfall, Agile, or Hybrid delivery, and generate the documentation roadmap.
metadata	{"use_when":"Use when the task matches meta-initialization skill and this skill's local workflow.","do_not_use_when":"Do not use when a more specific upstream or downstream skill owns the task, or when the required project context has not been prepared.","required_inputs":"Provide the target project or document, the relevant context files, scope constraints, and any domain or standards inputs referenced here.","workflow":"Follow the ordered steps, review gates, and local generation logic in this file before consulting deeper support files as needed.","quality_standards":"Keep outputs grounded in source context, traceable to stated standards, and specific enough to review or verify.","anti_patterns":"Do not fabricate missing requirements, skip human review gates, or substitute vague prose for verifiable documentation.","outputs":"Produce or update the document, scaffold, analysis, or phase artifact that this skill defines.","references":"Use `references/`, `templates/`, `README.md` when deeper detail is needed.","portable":true,"compatible_with":["claude-code","codex"]}

Meta-Initialization Skill

Inputs

Artefact	Required?	Purpose
Project objective, stakeholders, constraints, and delivery context	yes	Classify project and method
Existing documents and standards	conditional	Avoid duplicate or conflicting scaffolds

Outputs

Artefact	Consumer	Acceptance condition
Project profile and documentation roadmap	Project team	Method justified, phases ordered, owners and gates explicit

Capability contract

Read/search are required. Creating directories or documents requires explicit project-initialisation scope; never overwrite existing artefacts without inspection.

Degraded mode

Fallback with incomplete context: produce a provisional profile and question register, not a falsely definitive methodology.

Decision rules

Condition	Method	Failure avoided
Stable regulated scope and formal approvals	Waterfall	Missing governance evidence
Evolving product with iterative discovery	Agile	Premature specification lock-in
Formal gates plus iterative delivery	Hybrid	False either/or method choice

Domain anti-patterns

• Selecting Agile because requirements are missing. Fix: gather minimum project facts first.
• Generating every possible document. Fix: justify each artefact by risk and audience.
• Overwriting an existing roadmap. Fix: inspect and propose a merge.
• Treating the method as a label. Fix: define gates, cadence, owners, and evidence.
• Marking provisional assumptions as decisions. Fix: keep an explicit question register.

Process Workflow

flowchart TD
    Start[Run Skill] --> Scan[Scan Project Directory]
    Scan --> Detect[Detect Project Characteristics]
    Detect --> Q1{Existing<br/>methodology.md?}

    Q1 -->|Yes| Confirm[Confirm/Update Methodology]
    Q1 -->|No| Analyze[Analyze Project Type]

    Analyze --> Recommend[Recommend Methodology]
    Recommend --> UserChoice[User Selects Methodology]
    Confirm --> UserChoice

    UserChoice --> Generate[Generate Documentation Roadmap]
    Generate --> Init[Initialize Project Context]
    Init --> Output[Write methodology.md + doc_roadmap.md]
    Output --> Next[Show Next Steps]

    style UserChoice fill:#fff4e1
    style Generate fill:#e1f5ff

Step-by-Step Instructions

Step 1: Scan Project Directory

Scan ../ (parent project root) for indicators:

Project Type Indicators:

• package.json → Node.js/JavaScript project
• composer.json → PHP project
• requirements.txt / pyproject.toml → Python project
• .sln / .csproj → C# .NET project
• pom.xml / build.gradle → Java project
• Cargo.toml → Rust project
• go.mod → Go project

Existing Documentation:

• README.md → Check for methodology mentions
• ARCHITECTURE.md → Check for design approach
• projects//_context/methodology.md → Previous methodology selection

Development Artifacts:

• .git/ → Git repository (check for branch strategy)
• docker-compose.yml → Containerized deployment
• .github/workflows/ → CI/CD setup

Log all findings:

[Scan Report]
- Project Type: PHP (composer.json detected)
- Framework: Laravel (composer.json dependencies)
- Database: MySQL (migrations/ directory)
- Deployment: Docker (docker-compose.yml)
- Version Control: Git
- CI/CD: GitHub Actions
- Existing Docs: README.md, ARCHITECTURE.md
- Existing Context: None (first-time setup)

Step 2: Detect Project Characteristics

Based on scan results, determine:

Regulatory/Compliance Indicators

Check for keywords in README.md, documentation:

• "FDA", "FAA", "DOD", "medical device", "aerospace" → Regulated project
• "HIPAA", "GDPR", "SOC2", "PCI-DSS" → Compliance required
• "safety-critical", "life-safety" → Formal V&V needed

Project Maturity

• Greenfield (no existing code): Need comprehensive upfront planning
• Brownfield (existing codebase): Need documentation for existing system
• Startup/MVP: Fast iteration, evolving requirements
• Enterprise: Established processes, likely Waterfall or SAFe

Team Structure

Infer from repository activity (if Git history exists):

• Multiple contributors, PR workflow → Team environment
• Single contributor → Solo developer
• Frequent commits → Agile/iterative
• Infrequent, large commits → Waterfall/milestone-based

Step 3: Recommend Methodology

Based on detected characteristics, recommend:

Recommend Waterfall if:

• ✅ Regulatory/compliance keywords detected
• ✅ Project type: Medical, aerospace, government, automotive
• ✅ Fixed-scope contract language in docs
• ✅ Formal signoff processes mentioned
• ✅ Safety-critical system

Confidence Score: Calculate based on indicators (0-100%)

Example:

[Recommendation: Waterfall] (Confidence: 85%)

Reasons:
1. "FDA" and "medical device" detected in README.md
2. Formal compliance requirements (HIPAA)
3. Fixed-scope project (contract.pdf found)
4. Safety-critical indicators present

Recommended Pipeline:
- 02-requirements-engineering/waterfall/ (Full IEEE 830 SRS)
- 03-design-documentation/ (HLD + LLD for traceability)
- 09-governance-compliance/ (Traceability matrix, audit reports)

Recommend Agile if:

• ✅ Startup/MVP keywords in README
• ✅ Frequent commits (>10/week average)
• ✅ Sprint-based branch naming (feature/, sprint/)
• ✅ User-centric language ("user stories", "epics")
• ✅ No regulatory constraints

Example:

[Recommendation: Agile] (Confidence: 90%)

Reasons:
1. Startup project (package.json: version 0.3.2)
2. Frequent commits (average 15/week)
3. Feature branch workflow detected
4. No regulatory constraints detected
5. README mentions "MVP" and "rapid iteration"

Recommended Pipeline:
- 02-requirements-engineering/agile/ (User stories, backlog)
- 07-agile-artifacts/ (Sprint planning, DoD, DoR)
- Lightweight design docs (HLD only, no LLD)

Recommend Hybrid if:

• ✅ Mixed indicators (regulatory backend + agile frontend)
• ✅ Microservices architecture (some services regulated, others not)
• ✅ SAFe framework indicators
• ✅ Enterprise with agile teams

Example:

[Recommendation: Hybrid] (Confidence: 70%)

Reasons:
1. Microservices architecture detected (docker-compose.yml: 8 services)
2. Backend mentions "payment processing" (regulated)
3. Frontend is React SPA (rapid iteration)
4. Mix of waterfall (API) and agile (UI) branches

Recommended Pipeline:
- Backend: 02-requirements-engineering/waterfall/ (IEEE 830 SRS for payment service)
- Frontend: 02-requirements-engineering/agile/ (User stories for UI)
- Shared: 03-design-documentation/ (Unified HLD)

Step 4: User Selection

Present recommendation and allow user to confirm or override:

==================================================
SDLC-Docs-Engine: Methodology Selection
==================================================

Based on analysis of your project, we recommend:

📋 WATERFALL METHODOLOGY (Confidence: 85%)

Reasons:
- Regulated industry detected (FDA, medical device)
- Fixed-scope project indicators
- Safety-critical system

This recommendation suggests:
✅ Comprehensive upfront requirements (IEEE 830 SRS)
✅ Formal design documentation (HLD + LLD)
✅ Traceability matrix and audit reports
✅ Verification & Validation per IEEE 1012

==================================================

Do you want to:
[1] Accept recommendation (Waterfall)
[2] Choose Agile instead
[3] Choose Hybrid approach
[4] Show detailed comparison
[5] Skip methodology selection (manual setup)

Your choice:

Step 5: Generate Documentation Roadmap

Based on selected methodology, create doc_roadmap.md:

For Waterfall Projects:

# Documentation Roadmap: [Project Name]

**Methodology:** Waterfall
**Selected:** [Date]
**Rationale:** [Brief explanation from detection]

## Active Documentation Pipelines

### Phase 01: Strategic Vision (Optional but Recommended)
- [ ] 01-prd-generation → Product Requirements Document

### Phase 02: Requirements Engineering (MANDATORY)
- [ ] 02-requirements-engineering/waterfall/01-initialize-srs
- [ ] 02-requirements-engineering/waterfall/02-context-engineering
- [ ] 02-requirements-engineering/waterfall/03-descriptive-modeling
- [ ] 02-requirements-engineering/waterfall/04-interface-specification
- [ ] 02-requirements-engineering/waterfall/05-feature-decomposition
- [ ] 02-requirements-engineering/waterfall/06-logic-modeling
- [ ] 02-requirements-engineering/waterfall/07-attribute-mapping
- [ ] 02-requirements-engineering/waterfall/08-semantic-auditing

### Phase 03: Design Documentation (MANDATORY)
- [ ] 03-design-documentation/01-high-level-design
- [ ] 03-design-documentation/02-low-level-design
- [ ] 03-design-documentation/03-api-specification

### Phase 05: Testing Documentation (MANDATORY)
- [ ] 05-testing-documentation/01-test-strategy
- [ ] 05-testing-documentation/02-test-plans

### Phase 09: Governance & Compliance (MANDATORY)
- [ ] 09-governance-compliance/01-traceability-matrix
- [ ] 09-governance-compliance/02-audit-reports
- [ ] 09-governance-compliance/03-compliance-docs (if HIPAA/GDPR/SOC2)

## Disabled Pipelines

❌ **Phase 07: Agile Artifacts** (Not applicable for Waterfall)
❌ **Phase 02: Agile Requirements** (Using Waterfall SRS instead)

## Execution Order

1. **Week 1-2:** Phase 02 (Requirements) - Generate IEEE 830 SRS
  Phase 03 (Design) - HLD and LLD
  Phase 05 (Testing) - Test strategy and plans
  Phase 09 (Governance) - Traceability and audits

 6 weeks for complete documentation suite



Run: 02-requirements-engineering/waterfall/01-initialize-srs

For Agile Projects:

# Documentation Roadmap: [Project Name]

**Methodology:** Agile (Scrum)
**Selected:** [Date]
**Rationale:** [Brief explanation]

## Active Documentation Pipelines

### Phase 01: Strategic Vision (MANDATORY for Agile)
- [ ] 01-strategic-vision/01-prd-generation → Lightweight PRD

### Phase 02: Requirements Engineering (MANDATORY)
- [ ] 02-requirements-engineering/agile/01-user-story-generation
- [ ] 02-requirements-engineering/agile/02-acceptance-criteria
- [ ] 02-requirements-engineering/agile/03-story-mapping
- [ ] 02-requirements-engineering/agile/04-backlog-prioritization

### Phase 03: Design Documentation (Lightweight)
- [ ] 03-design-documentation/01-high-level-design (HLD only, skip LLD)

### Phase 07: Agile Artifacts (MANDATORY)
- [ ] 07-agile-artifacts/01-sprint-planning
- [ ] 07-agile-artifacts/02-definition-of-done
- [ ] 07-agile-artifacts/03-definition-of-ready

### Phase 08: End-User Documentation (Post-MVP)
- [ ] 08-end-user-documentation/01-user-manual

## Disabled Pipelines

❌ **Phase 02: Waterfall SRS** (Using Agile user stories instead)
❌ **Phase 09: Formal Governance** (Lightweight traceability via story tags)

## Execution Order

1. **Sprint 0:** Phase 01 (Vision) + Phase 02 (User Stories)
2. **Sprint 0:** Phase 03 (HLD) - Architectural overview
3. **Sprint 1-N:** Phase 07 (Agile Artifacts) - Ongoing per sprint
4. **Post-MVP:** Phase 08 (User Docs)

**Total Estimated Time:** 1-2 sprints for initial setup, then continuous

## Next Steps

Run: 01-strategic-vision/01-prd-generation
Then: 02-requirements-engineering/agile/01-user-story-generation

Step 6: Initialize Project Context

Check if projects/<ProjectName>/_context/ exists:

If missing:

mkdir -p projects/<ProjectName>/_context
echo "Project context directory created."

If exists:

[INFO] Project context directory already exists.
Checking for existing files...

Found:
- vision.md (last modified: 2026-01-15)
- features.md (last modified: 2026-01-20)

Missing:
- methodology.md (will be created)
- doc_roadmap.md (will be created)

Step 7: Write Output Files

File 1: projects/<ProjectName>/_context/methodology.md

Use template from templates/methodology.md.template (populated with detection results).

File 2: projects/<ProjectName>/_context/doc_roadmap.md

Use template from templates/doc_roadmap.md.template (populated based on methodology).

File 3: projects/<ProjectName>/_context/project_profile.md

# Project Profile

**Generated:** [Date]
**Project Type:** [Detected type]
**Framework:** [Detected framework]
**Database:** [Detected database]
**Deployment:** [Detected deployment]

## Characteristics

- **Regulatory Constraints:** [Yes/No - list standards]
- **Team Size:** [Inferred from git history]
- **Development Pace:** [Rapid/Moderate/Methodical]
- **Maturity:** [Greenfield/Brownfield/Startup/Enterprise]

## Recommended Methodology

**Selected:** [Waterfall/Agile/Hybrid]
**Confidence:** [XX%]

See `methodology.md` for full rationale.

Resources

• templates/methodology.md.template: Template for methodology selection
• templates/doc_roadmap.md.template: Template for documentation roadmap
• references/methodology-decision-tree.md: Detailed decision criteria
• references/detection-rules.md: Project characteristic detection rules

Common Pitfalls

❌ Skipping this skill

• Jumping directly to Phase 02 without methodology selection leads to wrong documentation approach

❌ Overriding recommendation without justification

• If you choose Agile for a regulated project, document WHY (e.g., regulatory approval already obtained)

❌ Not updating roadmap when project changes

• Re-run this skill if project characteristics change (e.g., startup gets FDA approval)

❌ Ignoring hybrid recommendations

• If recommended Hybrid, don't force pure Waterfall or Agile

Verification Checklist

Before proceeding to Phase 01/02:

• projects/<ProjectName>/_context/methodology.md exists and is populated
• projects/<ProjectName>/_context/doc_roadmap.md exists with checklist
• projects/<ProjectName>/_context/project_profile.md exists
• Methodology selection is documented with rationale
• Next steps are clear (which skill to run next)
• Team agrees with methodology choice (if applicable)

Integration with Other Phases

This skill enables:

• Phase 01 (Strategic Vision): Knows whether to generate PRD (Agile) or skip (Waterfall starts with SRS)
• Phase 02 (Requirements): Activates correct pipeline (waterfall/ or agile/)
• Phase 03 (Design): Determines depth (full HLD+LLD for Waterfall, lightweight HLD for Agile)
• Phase 07 (Agile Artifacts): Only activates if methodology is Agile or Hybrid
• Phase 09 (Governance): Determines formality level (full RTM for Waterfall, lightweight for Agile)

Upstream Dependencies:

• None (this is the first skill to run)

Downstream Consumers:

• All other phases read methodology.md to determine their execution mode

Example Output

See templates/ directory for complete examples:

• methodology.md.example - Waterfall selection for medical device
• methodology.md.example-agile - Agile selection for startup
• methodology.md.example-hybrid - Hybrid for enterprise SaaS

Maintenance & Updates

When to re-run this skill:

• Project characteristics change significantly (e.g., startup becomes enterprise)
• Regulatory status changes (e.g., FDA approval required mid-project)
• Team decides to switch methodologies
• Major pivot in product direction

Safe to re-run: Yes, this skill will prompt before overwriting existing files.

---

Last Updated: 2026-02-07 Skill Version: 1.0.0 Maintained by: Peter Bamuhigire