Init Project

init-project

Overview

Scaffolds a project's AI-agent development protocol + DevSecOps guardrails + workflow ecosystem in one consistent pass: workflow discipline (CLAUDE.md/AGENTS.md), security policy, agent protocol docs, MCP policy, review prompts, spec/plan/codemap documentation scaffolding, a CI validation workflow, a SessionStart hook that nudges any future session if the protocol markers go missing, .gitignore hardening, security scripts, pre-commit, and .mcp.json. The goal isn't just files on disk — it's a working pipeline (/brainstorm → /spec-writer → /plan-writer + superpowers:writing-plans-self-improvement-assistant → superpowers:subagent-driven-development + superpowers:sdd-self-improvement-assistant → /qa-master) that a future agent session, or a new teammate who never ran this skill themselves, can pick up cold and follow correctly — because the protocol and its enforcement both live in the repo, not in any one person's local skill library. Detects the stack and tailors content. Idempotent — never clobbers existing files. Scaffold only — never installs, deploys, migrates, reads secrets, or adds dependencies.

When to Use

• A brand-new repo, or onboarding an existing repo that lacks these guardrails.
• The user asks to "set up the protocol / agent rules / DevSecOps guardrails", or runs /run-skill-generator.
• NOT for editing app code, and NOT a substitute for per-feature brainstorming.

Procedure

1. Detect the stack (cheap reads only)

Read whatever exists: package.json, composer.json, go.mod, requirements.txt/pyproject.toml, Cargo.toml, Dockerfile, prisma/schema.prisma, *.csproj. Determine:

• Framework (Next.js/Node/Laravel/Django/Go/…), package manager (npm/pnpm/yarn/composer/pip), language (TS/JS/PHP/Py/Go), ORM/DB (Prisma/Eloquent/…), test runner, deploy hint (Dockerfile/CI).
• Sensitive surfaces present: auth, payment, webhook, file upload, user input, API routes, server actions, env/secret, schema/migration. Run git status --short --branch and list existing files so you know what to MERGE vs CREATE.

2. Confirm (one short message)

State detected stack + project name + the file manifest (below) + "I will merge into existing CLAUDE.md/AGENTS.md, skip other existing files." Proceed unless the user objects.

3. Generate the manifest (idempotent)

For each file: create from the matching templates/ file in this skill's directory, adapting placeholders to the detected stack. If the file already exists, follow the Idempotency rules below — never overwrite blindly.

4. Apply stack adaptations

5. Verify completeness (before reporting — do NOT skip)

Re-list the full manifest and confirm each target file now exists on disk (ls / test -f). Create any that are still missing. Do not stop until every manifest item is present or explicitly skipped because it pre-existed. A partial scaffold (e.g. only CLAUDE.md + AGENTS.md) is a FAILURE — the most common one. If you are running low on budget, prioritize creating the remaining files over writing prose.

6. Report (always)

End with: Summary · Files created · Files merged · Files skipped (already present) · Stack detected · Next steps. Next steps to list:

• Set GITHUB_PERSONAL_ACCESS_TOKEN env var (for github MCP)
• Run pre-commit install
• Install CLIs (gitleaks, trivy, semgrep, uv) if missing
• Reload the agent so .mcp.json is picked up
• If .claude/settings.json was just created (not merged into an existing one), open /hooks once or restart the session — the settings watcher only watches directories that already had a settings file when the session started, so a brand-new .claude/ may need one manual reload before the SessionStart hook activates
• Workflow pipeline available: /brainstorm → /spec-writer → /plan-writer + superpowers:writing-plans-self-improvement-assistant → [user approve] → superpowers:subagent-driven-development + superpowers:sdd-self-improvement-assistant → /qa-master. Full combo table in AGENTS.md § Workflow Skills.
• ECC agents ready: sub-agents typescript-reviewer, security-reviewer, react-reviewer, database-reviewer sudah tersedia di ~/.claude/agents/ — dispatch untuk review sebelum commit
• Once real code exists: consider running ecc workspace-surface-audit for a stack-specific skill/agent/MCP recommendation, and update-codemaps to fill in docs/CODEMAPS/README.md — both optional, not run automatically by this skill

Never claim it is "100% secure".

Inline snippets

.gitignore hardening (append only the lines that are missing):

.env
.env.*
!.env.example
*.pem
*.key
id_rsa
id_ed25519
node_modules
vendor
dist
build
.next
coverage
playwright-report
test-results

Security scripts (merge into the package manager manifest, keep existing scripts; Node example — adapt per stack):

"typecheck": "tsc --noEmit",
"security:secrets": "gitleaks detect --source . --verbose",
"security:code": "semgrep scan --config auto",
"security:fs": "trivy fs .",
"security:npm": "npm audit --audit-level=high",
"security:all": "npm run security:secrets && npm run security:code && npm run security:fs && npm run security:npm",
"predeploy": "npm run lint && npm run typecheck && npm run build && npm run security:all"

Idempotency rules

• Never overwrite an existing file. CLAUDE.md/AGENTS.md → merge the protocol blocks only (check a marker heading like ## ⚙️ Alur Kerja Wajib before inserting). Other files → skip and report "already present".
• .gitignore / scripts → add only missing entries; never remove the user's lines.
• .claude/settings.json → JSON-merge, never text-append. Read the file first. If it doesn't exist, create it from templates/settings.json. If it exists: parse it, check whether any existing hooks.SessionStart[].hooks[] entry already contains the string Alur Kerja Wajib in its command (our dedup marker) — if yes, skip and report "already present"; if no, append (don't replace) a new entry to the hooks.SessionStart array (create the array if the key is missing), preserving every other key in the file untouched. Re-parse the written file afterward to confirm it's still valid JSON — a broken settings.json silently disables every other setting in it.
• If unsure whether a merge is safe, skip and tell the user what to add manually.

Why this hook exists: the protocol markers in CLAUDE.md/AGENTS.md only standardize a team if everyone's agent actually reads them. A human onboarding a new repo can forget to run /init-project, and a new teammate's AI session has no way to know this skill exists unless the repo itself nudges it. This SessionStart hook is committed with the rest of the manifest specifically so the check travels with the repo, not with any one person's local skill library.

Hard limits (never do)

• Never read, print, copy, or create real secret files (.env*, *.pem, *.key, id_rsa, id_ed25519). A generated .env.example must contain placeholders only (from documented var names, not by reading any .env).
• Never install packages, deploy, run migrations, access a production DB, or run destructive commands.
• Never hardcode a token in any file — GitHub MCP token goes in an env var.

Common mistakes

• Stopping at CLAUDE.md/AGENTS.md — generate the FULL manifest (the baseline failure was missing MCP docs, review prompts, .mcp.json, the package scripts, and — as of the ecosystem expansion — the docs/superpowers/specs, docs/superpowers/plans, docs/CODEMAPS seeds, .github/workflows/ci.yml, and .claude/settings.json). A scaffold that leaves CLAUDE.md referencing folders that don't exist on disk is a FAILURE.
• Text-appending into .claude/settings.json instead of JSON-merging — this file is structured JSON; a naive text insert (like the .gitignore append) will corrupt it and silently disable every other setting in the file. Always parse, merge, re-serialize, and re-validate.
• Pairing skills incorrectly — writing-plans-self-improvement-assistant and sdd-self-improvement-assistant are companions, not substitutes, for /plan-writer and superpowers:subagent-driven-development. Don't document one without the other, and don't invent a self-improvement-assistant pairing for skills that don't have one (/brainstorm, /spec-writer, /qa-master).
• Overwriting existing docs — always merge/skip.
• Generic, un-adapted content — fill the placeholders from the detected stack; trim checklists that don't apply.
• Running installs — this skill scaffolds files; installs are a separate one-time PC step.