3s-codex-workflow - GitLite

KO | EN

gitlite — search

#python #llm #go #rust #deep-learning #linux #docker #java #awesome #kubernetes #pytorch #ios #openai #open-source

3s-codex-workflow

(★ 92)

Three lightweight Codex workflow skills for goal clarity, evidence-based review, and safe public research.

파일 탐색기

최종 버전 다운로드 (.zip)

- - boundary-safety-report.md
  - bug-report.md
- - validate.yml
- pull_request_template.md
- philosophy.md
- workflow.md
- - 01-normal-positive.md
  - 02-boundary.md
  - 03-should-not-use.md
- - 01-normal-positive.md
  - 02-boundary.md
  - 03-should-not-use.md
- - 01-normal-positive.md
  - 02-boundary.md
  - 03-should-not-use.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - acceptance-cases.md
- - acceptance-cases.md
- - acceptance-cases.md
- - acceptance-cases.md
- validate_v01.py
.gitignore
CHANGELOG.md
CONTRIBUTING.md
LICENSE
README.md
SECURITY.md

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 3S Codex Workflow Toolkit

Build real software with Codex without losing the goal.

**What is it?** An independent open-source toolkit of three Codex Skills for clarifying product goals, reviewing repository evidence, and researching public sources safely.

**Why does it exist?** Coding agents can start too early, claim completion too loosely, or let new research silently change active work.

**Who is it for?** Developers, maintainers, and product owners using Codex or another compatible coding agent on real repositories.

**What problem does it solve?** It separates goal definition, implementation, evidence review, and external research so each step keeps its authority boundary.

**How do I try it?** Choose one Skill directory, install or register it with the mechanism supported by your current Codex version and surface, verify that Codex discovers it, then invoke it by name for a matching task.

This is not a prompt collection. It is a lightweight workflow discipline:

Goal → Build → Review → Gate → Release
    Research → Candidate → Owner Decision

## What It Is

3S Codex Workflow Toolkit is a small repository of three focused, self-contained Skills:

- Product Goal Clarifier defines an implementation-ready target before coding.
- Codex Project Reviewer checks completion claims against repository evidence.
- Safe Public Research studies public sources without turning findings into unapproved implementation.

The toolkit is designed around practical product-development workflows and tested against the acceptance cases in this repository. It is a Skill toolkit, not a plugin, application, MCP server, or agent orchestrator.

## Why It Exists

The toolkit addresses three recurring failure modes:

1. **Agent starts coding before the goal is clear.** The result may be functional but solve the wrong problem.
2. **Agent claims completion without enough evidence.** Passing claims can hide missing tests, uncommitted changes, gate failures, or Scope drift.
3. **New research silently changes the current implementation.** A useful external idea can bypass owner review and become accidental Scope.

Each Skill owns one responsibility and stops at its boundary.

## The Three Skills

### Product Goal Clarifier

- **Use when:** the product idea, Scope, Constraints, success measures, Non-goals, or Milestones are unclear.
- **Do not use when:** the task is implementation, repository review, or public research.
- **Primary output:** a Product Goal Brief with Goal, Scope, Constraints, Success Criteria, Non-goals, Milestones, and READY or NOT_READY.
- **Skill:** [skills/product-goal-clarifier/SKILL.md](skills/product-goal-clarifier/SKILL.md)

### Codex Project Reviewer

- **Use when:** a completion claim must be checked against Goal, Scope, Git baseline, implementation, tests, gate evidence, and uncommitted changes.
- **Do not use when:** the Goal is still undefined or the user wants automatic repair.
- **Primary output:** a read-only Project Review Report with ACCEPT, REVISE, or STOP.
- **Skill:** [skills/codex-project-reviewer/SKILL.md](skills/codex-project-reviewer/SKILL.md)

### Safe Public Research

- **Use when:** public GitHub projects, open-source software, competitors, products, standards, or papers need source-traceable research.
- **Do not use when:** the request requires private access, bypassing controls, repository modification, approval, or implementation.
- **Primary output:** a Public Research Report that separates RESEARCH, CANDIDATE, DECISION, and IMPLEMENTATION.
- **Skill:** [skills/safe-public-research/SKILL.md](skills/safe-public-research/SKILL.md)

## Workflow

Primary path:

IDEA
      ↓
    Product Goal Clarifier
      ↓
    GOAL
      ↓
    BUILD
      ↓
    Codex Project Reviewer
      ↓
    ACCEPT / REVISE / STOP

Research path:

External Research
      ↓
    Safe Public Research
      ↓
    RESEARCH
      ↓
    CANDIDATE
      ↓
    Owner Decision

The research path never changes the primary path by itself. Candidate is not approval, and research is not implementation.

See [docs/workflow.md](docs/workflow.md) for responsibility boundaries and [docs/philosophy.md](docs/philosophy.md) for the six design principles.

## Quick Start

Each Skill is a self-contained repository directory with `SKILL.md` as its core entry point:

- `skills/product-goal-clarifier/`
- `skills/codex-project-reviewer/`
- `skills/safe-public-research/`

To use one:

1. Inspect the three directories and choose the Skill matching your task.
2. Install or register that directory using the Skill installation or discovery mechanism supported by your current Codex version and surface.
3. Verify that Codex discovers the Skill.
4. Invoke the Skill by name using the interface available in that Codex surface.

Installation and discovery mechanisms may evolve across Codex versions and surfaces. Use OpenAI's current Skills documentation or the built-in Skill installer available in your Codex environment as the authority. If your current Codex provides a built-in installer, it may support installing a Skill from a public GitHub repository or repository path after this project is published.

This repository does not claim that one hard-coded user directory is universally correct or permanently supported. Do not use a placeholder GitHub URL; select this repository through the current installer only after its real public location exists.

## Usage

Use natural language; these examples are not special slash commands:

- “Use the product-goal-clarifier skill to turn this idea into an implementation-ready goal.”
- “Review the current repository using codex-project-reviewer.”
- “Research this public repository using safe-public-research, but keep findings out of the current implementation.”

## Examples

- [Product Goal Clarifier examples](examples/product-goal-clarifier/)
- [Codex Project Reviewer examples](examples/codex-project-reviewer/)
- [Safe Public Research examples](examples/safe-public-research/)

Each directory contains a normal positive scenario, a boundary scenario, and a should-not-use scenario.

## Validation

The validator uses only the Python standard library:

python tests/validate_v01.py

Exit code 0 means the repository structure and documented contracts pass. A nonzero exit code prints specific failures.

The acceptance contracts are under [tests](tests/) and include 18 Skill-level cases plus 3 cross-Skill boundary cases.

## Contributing

Read [CONTRIBUTING.md](CONTRIBUTING.md) before proposing a change. Behavioral changes require focused acceptance evidence and must preserve responsibility boundaries.

## Security

Read [SECURITY.md](SECURITY.md) before reporting unsafe instructions, unauthorized actions, credential exposure, or research-to-implementation leakage.

## License

This repository candidate uses the [MIT License](LICENSE).