ddalggak

ddalggak is a workflow skill for turning GitHub issues into planned, parallel, reviewed, and recoverable implementation work. This repository projects one skill to two co-equal runtimes: the Codex App skill source (.codex/skills/ddalggak/) and the Claude Code skill (ddalggak/, with a CLI bridge for setup). Each root is canonical for its own runtime, and npm run verify:projections enforces parity between them.

npm release status: this package is being prepared for publication, but this README does not claim a live npm package until registry visibility is proven by the release follow-up audit.

AI-readable Documentation Index

This repository ships a package-local llms.txt index for humans and AI coding agents that need a compact map of the skill entrypoints, workflow references, and package verification surfaces. It is a repository/package navigation file only; it is not a crawler directive, hosted API promise, or publication of private project state.

Instruction Projection

AGENTS.md (repository root) is a thin cross-runtime adapter for agent runtimes that look for a repo-root instruction file (such as OpenAI Codex cloud agents). It is a projection pointer only — it names the canonical policy sources and states the side-effect boundary in short form. It does not duplicate or extend the workflow policy in this README or .codex/skills/ddalggak/SKILL.md.

Maintainer rule: instruction projection adapters are not canonical policy. Canonical policy lives in README.md and SKILL.md. If an adapter file and a canonical source conflict, the canonical source wins and the adapter must be updated to match. npm run verify:projections enforces required anchors, forbidden sentinels, and thin-adapter size limits on AGENTS.md.

Codex App

For Codex App, use the repository-local skill source at .codex/skills/ddalggak/.

The invocation name is exactly ddalggak.

Example invocations:

[$ddalggak] plan "Split issue 22 into reviewable PR units"
[$ddalggak] start 22
[$ddalggak] status

ddalggak supports these subcommands (the same set in both runtimes):

• start: run issue-based implementation lanes.
• review: run independent review as an AI code quality gate, checking not only correctness but also scope, existing patterns, failure semantics, simplicity, and human reviewability before accepted-fix loops.
• status: inspect current lane, worktree, and PR state.
• plan: create an issue-ready implementation plan.
• issue: convert a plan into GitHub issues.
• clean: clean local state after merge verification.
• ship: commit, push, and open a draft PR for existing lane changes.
• retro: write a retrospective for the completed workflow.
• prompt: improve lane or review briefs.
• tune: align rough intent into a goal-ready brief.
• forge: convert done conditions into objective acceptance criteria.
• spark: draft a copyable runtime goal sentence with validation guidance.
• check: run a local diff check.
• getwiki: retrieve related wiki pages as read-only context for plan/review work.
• setwiki: save a source into the wiki through an approval-gated write workflow.

Codex App loads the skill from .codex/skills/ddalggak/; Claude Code loads it from ddalggak/. Neither root outranks the other — each is canonical for its own runtime, and the per-file parity contract is declared in core/projections.yaml and enforced by npm run verify:projections. The Claude Code setup path is described below.

Review as Quality Gate

ddalggak treats review as the guardrail that keeps AI-generated implementation work aligned with the codebase. AI implementation productivity remains with the implementation lanes, while review protects codebase direction, maintainability, and long-term ownership. Reviewers should block not only broken code, but also unnecessary abstraction, silent fallback, scope creep, pattern drift, and changes that humans cannot easily understand, modify, or delete later. Self-created complexity is a defect: forced modularization, helper/provider/wrapper sprawl, client-side patches that bypass server/request/data boundaries, and mock-only proof for auth or redirect behavior should all trigger review scrutiny.

For guardrail coverage, ddalggak also requires frontend rendered evidence gates, transitive fallback audits, missing-evidence severity classification, retrospective knowledge extraction categories, and analytics/privacy allowlist/denylist contracts. npm run verify:codex-skill checks stable anchors for these #44 guardrails across both runtime payloads so maintainer edits cannot silently remove them.

The Quality Lens Router chooses applicable gate families from request text, issue body/comments, PR files, and diff paths before plan, start, or review work. It records both applicable gates and skipped gates so backend-only work does not inherit frontend, deployment, or mobile review requirements by accident.

Review runs as a closed loop, not a one-shot pass. Accepted human-review feedback and failing-check triage are folded back into bounded accepted-fix iterations before APPROVE (human review feedback loop, CI failure triage loop). Before a PR is marked ready, ddalggak confirms the branch is rebased on a fresh base and that the ready conditions hold (rebase and ready gates).

Quality Defaults

• Branch names should describe the purpose of the change and must not include dates, timestamps, or generated time suffixes.
• Commit messages and PR descriptions must explain What changed and Why it changed. PR descriptions should also include Validation, Risk, and linked Issues.
• Issue-PRs by default: ddalggak should create one PR per independent issue. Use a single integration PR with issue-separated commits only when hard conflicts between issues make independent PRs unsafe.
• Runtime contract guardrails: ddalggak treats agent work as explicit runtime contracts rather than hidden autonomous loops.
  • Task Scope Contract: worker briefs and reviews must distinguish tool capability boundary from task scope contract, and treat out-of-scope diff as scope-expansion failure.
  • Context Assembly Manifest: plans, briefs, and reviews should name the issue/comments, repo conventions, loaded references, gates, assumptions, and blockers used as source context.
  • Resume Snapshot: paused, idle, CI, review/fix, and wave-transition states should record phase, issue/branch/PR, changed files, validation evidence, blocking gaps, next gate, and exact next command.
  • Control-flow ownership: approval, retry, side effects, force-push, production data touch, and verification completion remain conductor/reviewer-owned gates.
• plan, issue, and start should prove lane independence before claiming parallelism. The issue-PR / conflict-fallback matrix must include owned files, must-not-touch files, why each lane is independent, lane-specific evidence/validation, and the integration gate. Shared files, shared contracts, or runtime flips become serial commits in the same fallback PR; otherwise lanes remain independent issue PRs.
• Worker briefs should bias toward single-responsibility changes, pure functions where practical, TDD or unit-test coverage for core behavior, and the repository's naming plus companion-file conventions such as ABC.styles.tsx, ABC.constants.tsx, ABC.types.tsx, and ABC.parts.tsx when that pattern fits the codebase.
• Review should cite CI status as evidence, then focus on behavior intent, scope, code quality, architecture/domain boundaries, maintainability, and deletability.
• For no-argument start, status:unlocked issues are preferred candidates. If none exist, ddalggak falls back to open issues without mutating labels; status:locked issues are excluded without changing the label. Labels are selection hints, not workflow-outcome triggers.

Issue Forms — Pre-Admission Completeness Aid

GitHub Issue Forms (.github/ISSUE_TEMPLATE/ddalggak-issue.yml) provide a pre-admission schema that ensures issues arriving at the ddalggak workflow have minimum required context fields before agent planning begins.

What Issue Forms are:

• A pre-admission completeness aid that prompts contributors to include goal, source of truth, scope, owned files, validation, and blockers.
• A file-based schema surface that reduces the rate of missing context reaching the plan → issue → start pipeline.

What Issue Forms are NOT:

• Automatic execution approval: a submitted issue form does not authorize dobby:pending or any automated merge action.
• Immutable source of truth: form body remains user-editable untrusted text after submission. The agent must still verify all claims before acting.
• A replacement for Evidence Contract or wiki verification. Live evidence must still be collected post-implementation.

Caveats:

• blank_issues_enabled: false reduces contributor drift but does not prevent maintainers with write+ access from opening blank issues via GitHub UI.
• Labels listed in form defaults must exist in the live repo; GitHub does not auto-create missing labels.
• verifier/verify-issue-forms.mjs checks file existence, required field ids, non-empty labels/assignees, and caveat text presence at CI time.

Progressive Disclosure Budget

The always-loaded skill body should remain a thin router. Keep SKILL.md focused on routing invariants, code-modification permissions, global guardrails, subcommand dispatch, required reference maps, stop conditions, and verification checklists. Move long procedures to references/, reusable prompt/body shapes to templates/, and mechanical regression checks to scripts/ or future fixtures/ / evals/.

Maintainer target after the #94 thin-router pass:

• .codex/skills/ddalggak/SKILL.md: <= 450 lines and <= 35k chars.
• ddalggak/SKILL.md: <= 700 lines and <= 45k chars.

These are budget targets, not permission to delete guardrails. Routing, source-edit permissions, manual merge policy, issue-PR topology, Evidence Contract, Simplicity / Deletability, and URL target resolution must remain discoverable from the hot path.

Per-subcommand effective load (ddalggak/SKILL.md + required references + required templates, estimated tokens = ASCII chars / 4 + non-ASCII code points × 1.5) is measured against the budgets declared in core/projections.yaml subcommand_token_budgets. The estimate is a zero-dependency heuristic, not a real tokenizer: plain bytes / 4 undercounted multibyte content (a Korean syllable is 3 UTF-8 bytes but costs ~1.5–2 tokens), skewing files with ≥30% Korean content by ≥1.3x, so non-ASCII code points are weighted at 1.5 tokens each. Inside npm run verify the token budget step runs node scripts/project-runtime-assets.mjs --report --admission as an admission gate: any over-budget or missing-budget subcommand fails verify (exit 1). Running node scripts/project-runtime-assets.mjs --report on its own remains advisory and reports without failing.

Budget changes ship in a separate PR: a PR that changes the subcommand_token_budgets block must not also change measured skill content (ddalggak/**, .codex/**, core/commands/**), because raising the budget inside the same PR that grows the content would neutralize the admission gate's ratchet. Budget-only PRs, content-only PRs, and calibration PRs (budget plus non-measured files such as the estimation formula) are all allowed. CI enforces this on pull requests with node scripts/check-budget-isolation.mjs --base <ref> --head <ref>, which compares parsed budget values at the merge-base and head, so changes to other core/projections.yaml blocks or comment-only edits never count as budget changes.

Every ddalggak/references/*.md file must be either measured — named in some subcommand's required_references, so it counts against that subcommand's effective-load budget — or exempt, registered in core/projections.yaml reference_budget_exemptions with an absolute max_tokens cap. The admission gate (scripts/project-runtime-assets.mjs --report --admission) fails closed if a reference is neither (unbudgeted), is redundantly both, names a missing file (stale), or exceeds its cap on any root. This closes the hole where the conditional gates reachable only through the always-loaded references/quality-lens-router.md pointer (frontend-design-gate, react-code-quality-harness, vercel-agent-skills-gates) sat outside every budget and could grow without bound. Separately, each declared budget must stay <= its subcommand_token_ceilings value — a frozen absolute ceiling (current budget × 1.5) that a budget-only PR cannot ratchet past, blocking the two-PR bypass (raise the budget in one PR, grow content up to it in the next) that the per-PR isolation check alone does not catch. The reference_budget_exemptions and subcommand_token_ceilings blocks are not subcommand_token_budgets, so editing them is never flagged as a budget change by check-budget-isolation.mjs.

Claude Code

The CLI bridge builds /ddalggak <subcommand> slash commands for Claude Code. From a source checkout, run the CLI directly with Node.js:

node bin/ddalggak.js <subcommand> [args]

Examples:

node bin/ddalggak.js prompt "Improve retry handling"
node bin/ddalggak.js plan --print "Split issue 22 into reviewable PR units"
node bin/ddalggak.js tune --print "Clarify this implementation goal"
node bin/ddalggak.js spark --print "Draft the next runtime goal"
node bin/ddalggak.js start 22
node bin/ddalggak.js status
node bin/ddalggak.js status --local --json
node bin/ddalggak.js profile hermes --dry-run

When the claude CLI is not on PATH, or when the current terminal is non-interactive, the CLI prints the slash command to paste into Claude Code instead of spawning Claude Code.

Hermes-style Profile Proposal

ddalggak profile hermes proposes a global Claude Code profile change as a dry-run only. It reads the existing $CLAUDE_HOME/CLAUDE.md or ~/.claude/CLAUDE.md when present, then prints a unified diff proposal. It never writes CLAUDE.md, never writes settings.json, and intentionally has no --apply mode.

node bin/ddalggak.js profile hermes --dry-run
node bin/ddalggak.js profile hermes --print-claude-md-patch

The proposed profile adds Korean honorific/truth-first defaults, GitHub issue body/labels/comments checks, the ddalggak issue → plan → start → ship → review cycle, getwiki before plan/review, approval-gated setwiki, and a never-merge / never-auto-merge policy.

Note that Hermes is an unverified, aspirational parity target: it is declared in core/projections.yaml (status: aspirational, verified: false), but no script in this repository verifies Hermes parity, so npm run verify does not validate this profile against any runtime.

Setup

setup installs the Claude Code skill payload into ~/.claude/skills/ddalggak/:

node bin/ddalggak.js setup

Use CLAUDE_HOME or --target to choose a different Claude Code home:

CLAUDE_HOME=/path/to/.claude node bin/ddalggak.js setup
node bin/ddalggak.js setup --target /path/to/.claude

Package distribution, if any, is handled separately by maintainers. This usage guide does not claim that a release has been published.

CLI Options

Common subcommand options:

• --print: print only the /ddalggak <subcommand> ... slash command.
• --show-doc: print the matching SKILL.md section for the subcommand.

Goal-shaping subcommands:

• tune: produce an intent/scope brief for a future runtime goal.
• forge: turn a tuned brief into command/observation plus expected-result acceptance criteria.
• spark: produce the copyable runtime goal sentence and validation checklist.

profile hermes options:

• --dry-run: print a proposed patch without changing files. This is the default.
• --print-claude-md-patch: print only the proposed CLAUDE.md unified diff.
• --apply: not supported; apply profile changes manually after review if desired.

doctor options:

• ddalggak doctor runs read-only repo-source health checks over the skill payload: doc reachability (orphan references/templates unreachable from SKILL.md and core/commands required entries), dead pointers (references/*.md / templates/*.md targets that do not exist), completion-signal registry (signals named in the SKILL.md naming-rules section without a core/commands completion_signal or template definition), and projection-root file existence parity (SKILL.md, references/, templates/ only).
• --json: print the report as JSON (ok, per-check findings, and a notChecked disclosure list).
• --root <dir>: inspect a different repo checkout (defaults to the package checkout the CLI runs from).
• Exit codes: 0 clean, 1 findings detected, 2 usage error.
• Not checked: projection-root content parity (bytes/checksums), runtime-specific assets outside the shared skill surface (e.g. .codex agents/), and the installed skill under CLAUDE_HOME (use ddalggak status --local). Doctor only reports; it never fixes.

status --local options:

• --json: print package version, payload roots, installed path/version, source/installed checksums, missing required references/templates, extra installed payload files, and ok / stale / not-installed state as JSON. The JSON also includes an evidence section with runtime support, package manifest status (not-installed / absent / malformed / stale / present), payload counts/checksum match, and a short next action.

setup options:

• --dry-run: print planned actions without changing the filesystem.
• --force: skip the installed-version comparison and overwrite the existing installation.
• --no-backup: remove the existing installation before copying without creating a backup.
• --target <path>: choose the install root. This takes priority over $CLAUDE_HOME and ~/.claude.

Install path priority is --target <path>, then $CLAUDE_HOME, then ~/.claude.

Release Helper Scripts

Maintainers can use the release helper scripts to prepare future npm release workflows without publishing anything from local development:

node scripts/release-plan.mjs v0.1.1
node scripts/release-plan.mjs v0.2.0-alpha.1
node scripts/bump-release-version.mjs v0.1.1

release-plan.mjs accepts strict v-prefixed semver tags only and emits GitHub Actions-style key=value lines for tag, version, isPrerelease, npmDistTag, and githubReleaseType. Stable tags use the latest npm dist-tag; prerelease tags use next.

bump-release-version.mjs updates only package.json and rejects non-upgrade targets. The npm lookup/publish classifier scripts are intended for CI workflows to distinguish idempotent 404/already-published states from unknown failures.

These helpers do not create tags, GitHub releases, or npm publications.

Release Drafter

Merged PRs on master refresh a draft GitHub release through Release Drafter. The draft tag and name are derived from the current package version:

• tag: draft-v<package.version>
• name: Draft v<package.version>

Manual dry-runs can inspect another ref without updating the draft:

# GitHub Actions → Release Drafter → Run workflow
# target_ref: your branch or SHA
# dry_run: true

Non-dry-run manual draft updates are intentionally guarded to master only. Release Drafter only updates draft release notes; it does not create final release tags and does not publish to npm.

Manual Release Bump

Maintainers can run the Manual Release Bump workflow to prepare a version bump PR without mutating master directly:

• tag: target release tag or version, such as v0.2.0 or 0.2.0-alpha.1
• base_ref: defaults to master
• dry_run: defaults to false

Dry-runs apply the bump in the ephemeral Actions checkout, verify that only package.json changed, run npm run verify, and write a summary without pushing a branch or opening a PR.

Non-dry-run executions create or reuse a deterministic draft PR branch for the same tag and base_ref, label the PR with skip-changelog and release, and describe the required order: candidate verification, tag creation, then publish approval. The workflow does not create tags, finalize GitHub releases, or publish to npm.

Release Candidate Verification

The Release Candidate Verification workflow verifies a version bump merge commit before any final release tag is created:

• push trigger: runs on master when package.json changes
• manual trigger: requires an exact 40-character target_sha

The workflow checks out the exact SHA, confirms HEAD matches the requested commit, compares the previous package.json version with the candidate version, and writes a skip summary when package.json changed without a version bump.

For real release candidates, it fails if v<package.version> already exists, runs npm run verify, packs the package with npm pack --json, installs the packed tarball in a temporary project, and exercises npx ddalggak --help plus npx ddalggak plan --show-doc. The summary records the verified SHA, version, next tag, and packed tarball name. This workflow only verifies the candidate; it does not create tags, finalize GitHub releases, or publish to npm.

Release Publish

The Release Publish workflow publishes an existing release tag after protected release environment approval. It runs for pushed v*.*.* tags or a manual dispatch that names an existing v-prefixed semver tag.

Before publish, the workflow checks out the tagged ref, verifies that package.json version matches the tag, runs npm run verify, packs the artifact with npm pack --json, installs the packed tarball in a temporary project, and exercises npx ddalggak --help plus npx ddalggak plan --show-doc. After protected approval, it checks out the verified commit SHA and publishes that same verified tarball artifact instead of re-resolving the tag name.

Publishing prioritizes npm trusted publishing with provenance. A NPM_TOKEN fallback is supported for registries or repository settings where trusted publishing is not ready yet, but trusted publishing should remain the primary path. Stable releases publish with the latest dist-tag, prereleases publish with the next dist-tag, and already-published exact versions are treated as a successful skip for safe reruns.

Release Published Follow-up Audit

The Release Published Follow-up Audit workflow runs after a GitHub release is published, or manually for an existing tag. It verifies the GitHub release and npm registry metadata, including package name, version, bin.ddalggak, license, and repository URL.

After registry metadata verification, the workflow collects content-light provenance/signature evidence. The audit summary records the following fields:

• node_npm_requirement_status — Node.js and npm version in the runner at audit time.
• trusted_publisher_identity_status — recorded as manual-confirmed because npm Trusted Publisher settings cannot be proven from CI alone.
• workflow_filename_match — the workflow filename used for trusted publishing (release.yml).
• environment_protection_status — confirms the publish job is gated by the release protected environment.
• token_fallback_used — true when NPM_TOKEN fallback was used; false when the trusted publishing path ran. When true, provenance_status is set to provenance-limited.
• provenance_status — trusted-publishing-path (OIDC-based publish with --provenance) or provenance-limited (NPM_TOKEN fallback, no OIDC provenance).
• registry_signature_status — result of npm audit signatures; distinguished states: verified, unsupported-or-no-attestation, or unverified-exit=<N>.
• release_tarball_artifact_name, artifact_id, artifact_digest, download_digest_validation, retention_days — tarball artifact identity and integrity fields collected from the GitHub Actions artifact API and npm registry.
• hidden_files_included, overwrite_policy — static policy facts about the packed tarball.
• attestation_status — result of gh attestation verify; states include verified, no-attestation-found, unsupported, or unverified.

Important caveat: provenance and attestation confirm publish-time identity binding only. They are not a guarantee of semantic safety — a package with verified provenance is not automatically free of vulnerabilities or correct in behavior. Fields that cannot be collected are recorded as unknown and are not promoted to a passing status.

External Release Setup Checklist

Before the first npm publication, maintainers must complete the external settings that cannot be proven from this repository alone:

• npm organization/scope: confirm that the publishing account has permission to publish public packages under @jeremyfellaz and that the package name in package.json remains @jeremyfellaz/ddalggak.
• npm authentication: prefer npm Trusted Publishing for the GitHub Actions Release Publish workflow. If Trusted Publishing is not available for the package yet, configure a repository or environment secret named NPM_TOKEN as the documented fallback. Never paste token values into issues, PRs, workflow logs, or release notes.
• GitHub environment: create or verify a protected environment named release and require maintainer approval before the publish_to_npm job can proceed.
• Repository labels used by release automation and changelog grouping: release, skip-changelog, enhancement, bug, documentation, docs, test, ci, chore, maintenance, feat, and fix.
• Truthfulness gate: until the follow-up audit verifies npm registry metadata for the published version, do not change this README or the GitHub About homepage to claim that the npm package URL is live.

First Publish Runbook

Use this order for the first real publication. The agent must not merge PRs, create final tags, approve protected environments, or publish on behalf of maintainers.

1. Confirm the external setup checklist above, including @jeremyfellaz publish permission, npm auth path, and protected release environment approval.
2. Run the Manual Release Bump workflow for the intended vX.Y.Z tag. Review the generated draft PR and merge it manually only after it is correct.
3. Let Release Candidate Verification run on the merged package.json version change, or dispatch it manually with the exact target SHA. Confirm that it verifies the SHA, tag availability, package verification, package packing, and smoke install.
4. Create the final Git tag only after candidate verification identifies the exact release SHA and the maintainer has decided to release that SHA.
5. Let Release Publish run from the tag, or dispatch it with the existing tag. Approve the protected release environment only after verifying the verify_tagged_ref job logs/outputs, uploaded tarball name, tag, SHA, and package version.
6. Confirm publish completion from the workflow summary. If Trusted Publishing fails and NPM_TOKEN fallback is configured, ensure the fallback path still publishes the same verified tarball artifact.
7. Run or wait for Release Published Follow-up Audit. Treat the release as externally verified only after the audit confirms the GitHub release and npm registry metadata.
8. Only after the follow-up audit passes, update user-facing metadata such as the GitHub About homepage or README install guidance to point at the live npm package URL.

Maintainer Verification

Before changing the CLI bridge, Codex skill source, release helpers, or package artifact boundaries, maintainers should run the relevant local checks:

npm run verify

npm run verify runs the CLI smoke suite, Codex skill verifier, ddalggak readiness eval fixtures, release helper tests, release drafter tests, manual release bump tests, release candidate tests, release publish tests, security posture evidence tests/report, PR check evidence bundle tests, and npm package artifact inspection. For focused diagnostics, maintainers can still run each underlying check directly:

npm test
npm run verify:codex-skill
npm run eval:ddalggak-readiness
npm run test:release-helpers
npm run test:release-drafter
npm run test:manual-release-bump
npm run test:release-candidate
npm run test:release-publish
npm run verify:security-posture
npm run test:security-posture
npm run test:pr-check-evidence
env npm_config_cache=/tmp/ddalggak-npm-cache npm pack --dry-run --ignore-scripts --loglevel=silent

Use npm test for CLI setup and dispatch behavior, including setup safety/idempotency, status --local installed-skill parity states, dispatch quoting edge cases, and every subcommand --show-doc surface. Use npm run verify:codex-skill for Codex skill source, metadata, Quality Lens Router anchors, subcommand routing changes, progressive-disclosure budgets, required reference/template maps, Claude/Codex payload parity, detail-template regression guards, and npm package artifact inclusion. Use npm run eval:ddalggak-readiness for mock JSON replay checks covering no-work mutation suppression, duplicate PR/comment suppression, evidence-gap readiness blocking, URL-beats-cwd mutation blocking, and hard-conflict fallback classification. Use npm run verify:security-posture for a read-only GitHub Actions posture inventory covering permissions blocks, action reference pinning, direct untrusted shell interpolation candidates, and official CodeQL/Dependency Review/Scorecard evidence presence. Use npm run test:pr-check-evidence for content-light PR check bundle normalization, failure classification, details URL preservation, and secret-like string redaction. Missing official scan evidence is reported separately and must not be described as proof that the repository is safe. Use the pack dry-run as an explicit maintainer-facing package artifact inspection as well.

Platform Support

macOS and Linux are the primary supported platforms. Windows support is best-effort when Node.js and the claude CLI environment are compatible.

Contributing

See CONTRIBUTING.md.