Old

# Codex `ywc-auth-implement` Skill Implementation Spec

> Status: Draft
> Scale: Medium
> Created: 2026-07-16
> Source: `/Users/yongwoon.kim/Desktop/yongwoon/source/private/develop-with-llm/docs/ywc-plans/260715-002-codex-auth-implement-skill.md`
> Target: `codex/` source bundle; the plugin package is generated from it.
> Amendment history: Iteration 1 (`ywc-spec-ready`) findings — Critical 1, Warning 6, Suggestion 3 — are fully merged into the sections below; no separate patch section remains.

## Purpose

Add a Codex-native `ywc-auth-implement` orchestration skill. It turns an application's authentication intent into a policy-backed, library-first, security-gated implementation route without assuming Claude-only agents exist.

## Anchors

| Anchor | Decision |
|---|---|
| What | Add `codex/skills/ywc-auth-implement/` with instructions, Codex metadata, localized READMEs, focused references, and regression evals. |
| Why | Authentication work needs explicit policy decisions, established-library reuse, and mandatory security/E2E gates rather than ad-hoc scaffolding. |
| Out of Scope | Application auth code, a new Codex custom agent, pre-seeded stack playbooks, legal approval, Claude Code bundle changes, and manual release-metadata edits. |
| Done When | The new skill meets the Codex bundle contract, covers the required routes (including `$ywc-task-generator`), installs into a disposable `CODEX_HOME`, and passes source/plugin validation. |

## Existing Constraints Touched

| Artifact | Verified behavior | Plan interaction |
|---|---|---|
| `AGENTS.md:5-20` | Codex skills require `SKILL.md`, four Tier-1 README locales, and `agents/openai.yaml`; Tier-2 locales are maintained when shipped. | Add six README locales and UI metadata. |
| `codex/AGENTS.md:5-27` | `codex/skills/` is source; `plugins/ywc-agent-toolkit/skills/` is generated by `scripts/sync-codex-plugin.sh`. | Edit only source, then synchronize. |
| `scripts/validate.sh:39-84` | Validation enforces skill name/frontmatter, Tier-1 READMEs, and metadata fields. | Keep frontmatter to `name` and `description`; provide required files. |
| `scripts/run-codex-skill-contract-evals.sh:16-68` | Every `evals/evals.json` needs valid JSON, skill name, unique numeric IDs, and prompts. | Add deterministic routing regression cases. |
| `scripts/check-codex-skill-descriptions.sh:7-13` | Skill descriptions are capped at 500 Unicode characters. | Keep triggers and anti-triggers concise. |
| `codex/skills/ywc-skill-author/SKILL.md` | New `ywc-*` skills use domain-specific Rationalization Defense, progressive disclosure, metadata, README locales, and evals. | Follow its artifact conventions. |
| `codex/skills/ywc-code-gen/SKILL.md:36-44,167-191` | `--spec`, `--feature`, `--tdd`, and `--review` drive implementation; auth/secret paths force security review. | Use it for application-code routing; do not invent workers. |
| `codex/skills/ywc-task-generator/SKILL.md` | Converts a `ywc-spec-ready`-approved spec into task directories before implementation; `ywc-code-gen` is not the task-decomposition step. | Insert this step between `$ywc-spec-ready` and `$ywc-code-gen`; never skip or auto-invoke it. |
| `codex/skills/ywc-security-audit/SKILL.md:30-65,87-96` | It takes `--code <path>` and emits severity findings, not a completion status. | This skill owns severity-to-status normalization. |
| `codex/skills/ywc-e2e-test-strategy/SKILL.md:18-48` | `--init`, `--audit`, and `--flow` are mutually exclusive; `--ci` is optional. | Select one setup/audit mode, then one flow per approved capability. |
| Current `codex/skills/` directory listing (verified this session: 44 skill directories, README.md states 42 — the published count is already stale before this spec) | The Codex skill count changes over time and must not be hardcoded as a literal target number in a spec. | FR-9 verifies the new count against the live directory listing rather than asserting a fixed "before → after" pair. |

## Scope

- Create `codex/skills/ywc-auth-implement/` with `SKILL.md`, `agents/openai.yaml`, `evals/evals.json`, six README locales, and focused references.
- Register the skill in `codex/skills/README.md`; update the Codex skill count in the root README locale files (`README.md`, `README.ko.md`, `README.ja.md`, `README.zh.md`, `README.es.md` — `README.en.md` does not exist and must not be created) to match the actual post-addition directory count.
- Synchronize `plugins/ywc-agent-toolkit/skills/` solely with `bash scripts/sync-codex-plugin.sh`.

## Out of Scope

- Implementing authentication, migrations, UI, secrets, or legal text in a consumer application.
- Adding/changing `codex/agents/*.toml` or depending on non-existent `ywc-backend-coder`, `ywc-frontend-coder`, or `ywc-doc-writer` agents.
- Creating `references/stack-*.md` in v1 or a fixed supported-stack allowlist.
- Editing `VERSION` or `CHANGELOG.md` directly; Release Please owns release metadata.
- Correcting the pre-existing 42-vs-44 drift in the root READMEs' Codex count as an unrelated fix; this spec only guarantees its own increment is correct relative to the live directory count at implementation time.

## Acceptance Criteria

- [ ] **AC1 — package contract:** the new directory contains the scoped artifacts; frontmatter has exactly `name: ywc-auth-implement` and `description`.
- [ ] **AC2 — activation and metadata:** description meets the 500-character limit, includes triggers and anti-triggers, and UI metadata matches the skill.
- [ ] **AC3 — read-only preflight:** preflight inspects and reports the required branch name, missing `.env.example` placeholder keys, unknown-stack research need, mandatory `new | extend | migrate` selection for existing auth, and legal-draft warning — without creating a branch or editing `.env.example` itself. Any user-authorized branch/env change happens as a separate, reviewable step that restores a clean tree before `$ywc-code-gen` is invoked. Git state that cannot be established (including detached HEAD) returns `NEEDS_CONTEXT` before any mutation.
- [ ] **AC4 — decision-grade interview with selected-method scoping:** `policy-interview.md` has nine `##` sections and remains mandatory even for OAuth-only work, but never requires both email/password and OAuth readiness fields when only one family is selected. Every selected method's fields (question, response/default, approval/deferred state) are recorded; unselected methods are recorded as excluded by approved policy and generate no E2E flow. No secret, access token, or real credential appears in output, logs, references, or eval fixtures.
- [ ] **AC5 — dynamic recommendation:** stack evidence and approved policy records drive recommendations; no stack playbook or supported-stack allowlist is introduced; insufficient evidence routes to `$ywc-tech-research`.
- [ ] **AC6 — Codex orchestration:** the route uses `$ywc-plan`, `$ywc-spec-ready`, `$ywc-task-generator`, `$ywc-code-gen --spec ... --feature ... --tdd --review`, `$ywc-security-audit --code ...`, `$ywc-e2e-test-strategy`, and optional `$ywc-create-pr`, without Claude-only agents. `$ywc-task-generator` output is only printed after `$ywc-spec-ready` reaches DONE and is never invoked automatically.
- [ ] **AC7 — safety and status:** direct JWT/password/secret crypto is not recommended; legal drafts state `법적 검토 전 임시본`; Critical/High findings skip E2E, PR proposal, and caching.
- [ ] **AC8 — output contract:** literal `## Output Format` describes summary fields and exactly one `DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT` value.
- [ ] **AC9 — evals with evidence fields:** cover happy path, existing-auth hard stop, unknown-stack research, direct-crypto refusal, and no-cache after Critical/High audit findings; each case includes `expected_behavior` and `anti_behavior` arrays validated by the existing JSON-schema runner, with instruction-level rejection additionally covered by `rationalization-evidence.md` forward tests.
- [ ] **AC10 — distribution:** source validation, eval validation, disposable install, plugin synchronization, and full repository validation pass, and the Codex skill count recorded in `README.md`, `README.ko.md`, `README.ja.md`, `README.zh.md`, and `README.es.md` matches the live `codex/skills/` directory count at verification time.

## Functional Requirements

### FR-1: Scaffold and progressive disclosure

Create the standard Codex artifact set. Keep `SKILL.md` below 500 lines; place reusable checklists, interview fields, templates, detailed transitions, and evidence in direct `references/` links. Generate `agents/openai.yaml` from the final skill content rather than preserving stale UI text.

### FR-2: Rationalization Defense

Provide at least five evidence-linked Excuse/Reality rows. Reject skipping the interview for OAuth-only work, direct crypto/JWT implementation, ignoring existing auth, caching before security/E2E success, and presenting legal text as final advice. `references/rationalization-evidence.md` records a focused baseline failure and post-draft forward-test per behavior; it does not run application code.

### FR-3: Read-only idempotent preflight

Inspect project guidance, manifests, framework/DB evidence, branch, `.env.example`, and `.gitignore` before questions. Preflight is read-only for branch and environment files: it may inspect and report the required branch name and missing placeholder keys, but it must not create a branch or edit `.env.example` before implementation routing.

1. Report whether `feature/<auth-slug>` already exists for reuse; only report that a long-lived branch is required as the base for a new one.
2. Report only missing secret placeholder keys; never write, overwrite, or expose a value itself at this stage.
3. Route insufficient stack evidence to `$ywc-tech-research` and resume after a decision.
4. When auth exists, return `NEEDS_CONTEXT` until the user chooses `new`, `extend`, or `migrate`; do not scaffold or dispatch before that choice.
5. Mark generated ToS/privacy material as `법적 검토 전 임시본`.
6. If the user explicitly authorizes the reported branch/env change, perform it as a separate, reviewable change and restore a clean working tree (for example, by committing only that change) before invoking `$ywc-code-gen`, which remains the primary owner of feature-branch creation and rejects a dirty tree.
7. When Git repository state, a base branch, or a clean-tree transition cannot be established, return `NEEDS_CONTEXT` before any mutation. Treat detached HEAD as needing an explicit target branch.
8. Point to the shared delegation contract via `../references/subagent-status-actions.md`; do not create a skill-local copy.

### FR-4: Policy interview with selected-method scoping

Ask the nine categories in one focused round. Separate approved values from recommended-but-deferred values. The interview remains mandatory even for OAuth-only work, but never requires both credential families — capture readiness only for each selected method:

- email/password configuration, reset, hashing-library boundary, breach/rate-limit policy only when email/password is selected;
- provider app registration, callback/redirect URI, consent-screen state, test identity, and non-secret readiness evidence for each selected OAuth provider;
- MFA enrollment/recovery; session storage, TTL, rotation, revocation, and devices; profile fields; deletion re-authentication and retention; shallow-RBAC roles/default/claim; consent version/capture/withdrawal; and abuse rate-limit, verification, and recovery controls, applied regardless of which credential family is selected.

Never place a client secret, access token, or real credential in output, logs, references, or eval fixtures. Unselected methods are recorded as excluded by approved policy, and their E2E flow is not generated. Application-facing questions and drafts use the target project's language convention, falling back to Korean only when none exists.

### FR-5: Dynamic recommendation and cache

Recommend battle-tested libraries or managed services only from stack evidence and approved (or explicitly deferred-with-risk) records. V1 starts with zero stack playbooks. If evidence is missing, use `generic-fallback.md` and route to `$ywc-tech-research`. A future playbook is cache-eligible only after zero Critical/High audit findings and applicable E2E success.

### FR-6: Specification and implementation routing

Pass the approved policy and recommendation to `$ywc-plan`. Medium/Large work must converge via `$ywc-spec-ready` before implementation. The required application-code route is:

`$ywc-plan → $ywc-spec-ready → $ywc-task-generator → $ywc-code-gen --spec <path> --feature <auth feature> --tdd --review`

`$ywc-task-generator` is printed only after `$ywc-spec-ready` reaches DONE; this skill must not skip task decomposition or invoke it automatically. `$ywc-code-gen`'s critical-path rule supplies implementation/security review. Documentation-only work may use a bounded general subagent with target, oracle, stop condition, evidence requirement, legal warning when relevant, and the shared status-actions reference.

### FR-7: Security, E2E, and PR gates

When application code uses `$ywc-code-gen --review`, consume its forced critical-path `$ywc-security-audit` result as the authoritative audit evidence; do not run a duplicate audit. For documentation-only delegation, invoke `$ywc-security-audit --code <changed-auth-path>` exactly once. In both cases, zero Critical and zero High is the only transition to E2E.

| Audit result | Route | Cache |
|---|---|---|
| Zero Critical and High | Continue to policy-conditioned E2E | Pending E2E pass |
| One or more Critical/High | `DONE_WITH_CONCERNS`; skip E2E/PR; remediate or replan, then re-audit | Not eligible |
| Command cannot run | `BLOCKED` with command/error evidence | Not eligible |
| Scope/trust boundary missing | `NEEDS_CONTEXT` with missing input | Not eligible |

Run exactly one `$ywc-e2e-test-strategy --init --ci` when Playwright is absent, or one `--audit` when it exists, then one `--flow` for each approved capability: email/password flows only when selected, deletion only when enabled, and one configured flow per selected OAuth provider. Record policy-excluded flows. After the mutually-exclusive init/audit operation and every required `--flow`, execute the target project's configured Playwright command — its documented package-manager script when available, or `npx playwright test` only when Playwright is installed and no project script exists — and record the exact command, exit code, and result summary.

| E2E result | Route | Cache / PR |
|---|---|---|
| Every applicable flow exits 0 | Continue | Eligible; offer PR only with user opt-in |
| Test command exits nonzero | `DONE_WITH_CONCERNS`; remediation then rerun | Not eligible; no PR offer |
| Server, provider credential, or test environment is absent | `BLOCKED`, unless the absent item is explicitly deferred and non-security | Not eligible; no PR offer |
| Unselected capability | Record its approved-policy exclusion | N/A |

A missing prerequisite is `DONE_WITH_CONCERNS` only when explicitly deferred and non-security; otherwise `BLOCKED`. Offer `$ywc-create-pr` only after gates pass and the user opts in.

### FR-8: Output/status contract

Include this table in the skill:

| Stage | Success transition | Stop / concern transition |
|---|---|---|
| Preflight | Policy interview | Existing-auth choice missing → `NEEDS_CONTEXT`; ungrantable clean-tree/branch state → `NEEDS_CONTEXT` |
| Policy interview | Recommendation | Required policy unresolved → `NEEDS_CONTEXT` |
| Recommendation | `$ywc-plan` → `$ywc-spec-ready` → `$ywc-task-generator` | Unknown/research-inconclusive stack → `BLOCKED` or `NEEDS_CONTEXT` |
| Implementation/docs delegation | Security audit | Worker status follows shared status actions |
| Security audit | Policy-conditioned E2E | Critical/High → `DONE_WITH_CONCERNS` plus skip/cache/remediation route |
| E2E | Optional PR proposal | Missing prerequisite follows FR-7 |
| Optional PR proposal | Completion | User decline is not failure and does not create a PR |

`DONE` requires every applicable non-optional gate. `DONE_WITH_CONCERNS` is limited to a declared non-security deferral or an unresolved Critical/High with the mandatory FR-7 skips. Output includes preflight, nine policy decisions, recommendation evidence, delegated work, security/E2E evidence when reached, cache decision, next handoff, and one completion status.

### FR-9: Documentation and catalogs

Write the six README locales in sibling formats. Add a `ywc-auth-implement` row to `codex/skills/README.md`. Update the Codex skill count in exactly these existing root README files — `README.md`, `README.ko.md`, `README.ja.md`, `README.zh.md`, and `README.es.md` — to the actual `codex/skills/` directory count measured at implementation time (do not carry forward any previously stated count as a literal target, since the published number may already be stale). Do not create `README.en.md`, which does not exist. Do not manually bump `VERSION` or edit `CHANGELOG.md`.

## Non-Functional Requirements

| Category | Requirement |
|---|---|
| Security | Prefer established libraries/services; never prescribe direct password hashing, token signing, or secret crypto. |
| Maintainability | SKILL.md stays below 500 lines; detailed content is directly linked. |
| Portability | Stack evidence is dynamic; no fixed framework allowlist. |
| Idempotency | Branch/env inspection is read-only and safe to rerun; any mutation is a separate, user-authorized, reviewable step. |
| Runtime fit | Depend only on installed Codex skills and bounded general subagent delegation. |
| Language | Bundle maintenance is Korean-first; target-project outputs use its convention. |

## Data Model

N/A — only skill/documentation artifacts change.

## API Contract

N/A — no network API changes. The structured output and completion status are the skill's documented interface.

## Edge Cases

- Existing auth without a `new | extend | migrate` choice: retain context and return `NEEDS_CONTEXT`.
- Unknown stack unresolved by research: return `BLOCKED` or `NEEDS_CONTEXT`, never a guessed library recommendation.
- Legal draft lacks its provisional notice: correct/re-dispatch it before completion.
- Critical/High findings: do not continue to E2E or PR.
- Missing provider credentials/test environment: classify via FR-7; do not claim E2E passed.
- Existing branch or placeholder: report for reuse/skip rather than duplicate; never create/edit during preflight itself.
- Detached HEAD or unresolvable Git state: return `NEEDS_CONTEXT` before any mutation.
- Root README Codex count already stale at spec-authoring time: FR-9 measures the live directory count rather than trusting a previously recorded number.

## Implementation Plan

1. Create the shell, frontmatter, UI metadata, six READMEs, and valid eval JSON using `ywc-skill-author` conventions.
2. Author the compact body: Rationalization Defense, read-only preflight, interview/recommendation, code-generation delegation (including `$ywc-task-generator`), security/E2E gates, and literal output contract.
3. Add policy interview, generic fallback, security checklist, legal template, rationalization evidence, and workflow-detail reference only if needed; do not add stack playbooks.
4. Add five routing evals with `expected_behavior`/`anti_behavior` arrays and assert no missing Claude-only worker name remains.
5. Update catalogs/counts against the live directory listing, synchronize the plugin package, and validate source and generated output.

## Verification

```bash
set -euo pipefail

python3 -m json.tool codex/skills/ywc-auth-implement/evals/evals.json >/dev/null
bash scripts/check-codex-skill-descriptions.sh --paths a-m
bash scripts/run-codex-skill-contract-evals.sh

for file in policy-interview.md security-checklist.md generic-fallback.md \
  legal-pages-template.md rationalization-evidence.md; do
  test -f "codex/skills/ywc-auth-implement/references/$file"
done

if rg -n 'ywc-(backend-coder|frontend-coder|doc-writer)' \
  codex/skills/ywc-auth-implement; then
  exit 1
fi

if ! rg -n '\$ywc-task-generator' codex/skills/ywc-auth-implement/SKILL.md >/dev/null; then
  echo "missing \$ywc-task-generator in the orchestration route" >&2
  exit 1
fi

# Verify the recorded Codex skill count matches the live directory listing —
# do not compare against a hardcoded number, since the published count drifts.
live_count="$(find codex/skills -mindepth 1 -maxdepth 1 -type d ! -name references ! -name scripts | wc -l | tr -d ' ')"
for f in README.md README.ko.md README.ja.md README.zh.md README.es.md; do
  if ! rg -q "Codex\s*\|\s*${live_count}\b|Codex.*${live_count}" "$f"; then
    echo "expected Codex count ${live_count} not found in $f" >&2
    exit 1
  fi
done

tmp_codex_home="$(mktemp -d)"
trap 'rm -rf "$tmp_codex_home"' EXIT
CODEX_HOME="$tmp_codex_home" bash scripts/install.sh --codex ywc-auth-implement
test -f "$tmp_codex_home/skills/ywc-auth-implement/SKILL.md"
test -f "$tmp_codex_home/skills/ywc-auth-implement/agents/openai.yaml"

bash scripts/sync-codex-plugin.sh
bash scripts/validate.sh
git diff --check
```

## Self-Consistency Pass

- **Pass A — AC ↔ FR:** AC1/2→FR-1; AC3→FR-3 (read-only preflight, clean-tree transition); AC4→FR-4 (selected-method records); AC5→FR-5; AC6→FR-6/8 (complete `$ywc-task-generator` route); AC7→FR-5/7 (audit evidence reuse plus executable E2E); AC8→FR-8; AC9→FR-2/7 (evaluable fixture fields); AC10→FR-1/9 (live-count catalogs). No orphan requirements.
- **Pass B — claim ↔ reality:** downstream names and flags are verified against current Codex skills; `$ywc-code-gen`'s clean-tree requirement and forced-audit behavior, `$ywc-spec-ready`'s `$ywc-task-generator` handoff, `$ywc-e2e-test-strategy` mode exclusivity, and the actual root README locale inventory (`README.md`, `README.ko.md`, `README.ja.md`, `README.zh.md`, `README.es.md`; no `README.en.md`) were confirmed by reading the repository this session. The security audit is a severity report and this skill owns terminal status. Source and generated plugin directories are distinct. The root READMEs' published Codex count (42) was found to already lag the live directory count (44) before this skill is even added — the spec accounts for this by measuring live count instead of asserting a fixed before/after pair.
- **Pass C — schema invariants:** N/A — no schema, migration, relation, or HTTP contract changes.

## Confidence Gate

`ywc-confidence-gate`: **95/100 — PROCEED**.

| Dimension | Score | Evidence |
|---|---:|---|
| Scope clarity | 96 | Source, target root, exclusions, and completion evidence are explicit. |
| Architecture compliance | 96 | Source/generated bundle boundary, `$ywc-task-generator` step, and read-only preflight are now consistent throughout every section — no superseded text remains. |
| Evidence quality | 95 | Relevant sibling command/status contracts were read, and the root README Codex count was independently verified against the live directory listing rather than trusted from the original spec. |
| Reuse verified | 93 | Existing planning, code-gen, task-generator, security, E2E, PR, and routing skills cover all lanes. |
| Root cause identified | 92 | The gap is Codex orchestration/documentation, not missing auth machinery; the count-drift risk is closed by verifying live state instead of hardcoding numbers. |

## Open Questions

N/A — stack playbooks intentionally start at zero, release metadata is automated, and the Codex-count target is resolved dynamically rather than left as an open number.

## References

- [Source Codex auth plan](</Users/yongwoon.kim/Desktop/yongwoon/source/private/develop-with-llm/docs/ywc-plans/260715-002-codex-auth-implement-skill.md>)
- [Claude Code parent plan](</Users/yongwoon.kim/Desktop/yongwoon/source/private/develop-with-llm/docs/ywc-plans/260715-002-claude-code-auth-implement-skill.md>)
- [Claude Code sibling plan](./claude_auth_implement_skill.md)

## Handoff

✅ Spec drafted: `docs/ywc-plans/codex_auth_implement_skill.md`

Next: run `ywc-spec-ready --spec docs/ywc-plans/codex_auth_implement_skill.md`. After it reaches DONE, run `ywc-task-generator` before implementation.