chore: scaffold ai-coding-skills repository structure

docs/repository-structure.md

@@ -0,0 +1,31 @@
+# Repository Structure
+
+This repository follows a superpowers-style organization for long-term maintainability.
+
+## Top-level directories
+
+- `skills/` → All installable skills.
+- `docs/` → Repository-level guidance.
+- `.codex/` → Codex-specific integration/config notes.
+- `.claude-plugin/` → Claude Code plugin metadata/integration notes.
+- `.opencode/plugins/` → OpenCode plugin metadata/integration notes.
+- `commands/` → Optional command wrappers.
+- `hooks/` → Optional pre/post hooks.
+- `tests/` → Regression tests for triggering/behavior.
+
+## Skill Folder Contract
+
+Each skill folder should contain at minimum:
+
+- `SKILL.md` (required)
+
+Optional:
+
+- `scripts/` (deterministic execution)
+- `references/` (detailed docs)
+- `assets/` (templates/resources)
+
+## Naming
+
+- lowercase + hyphen only
+- one skill per folder

docs/requirements-gate.md

@@ -0,0 +1,40 @@
+# Requirements Gate
+
+For any skill that depends on external skill sets (e.g., Superpowers), enforce these rules:
+
+## Mandatory Prerequisite Section in SKILL.md
+
+Include a `Prerequisites` section that states:
+
+- required dependency repo
+- required skill names
+- what happens if requirements are missing
+- exact remediation steps
+
+## Runtime/Flow Behavior
+
+If requirements are missing:
+
+1. Stop execution.
+2. Return a concise blocking message.
+3. Provide exact install/setup steps.
+4. Ask for confirmation once requirements are installed.
+
+## Suggested Block Message
+
+```text
+Cannot run <skill-name> yet.
+Missing required Superpower skills: <list>
+Install from: https://github.com/obra/superpowers
+After installation, tell me "requirements ready" and I’ll continue.
+```
+
+## Compatibility Requirement
+
+Each skill must declare support for:
+
+- Codex
+- Claude Code
+- OpenCode
+
+If one platform is unsupported, state it explicitly.