Skip to content
Back to search

molyanov-ai-dev

Intent-driven AI-First development methodology for Claude Code and Codex — Project Knowledge, user-spec planning, focused execution, and evidence-gated reviews.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/pavel-molyanov--molyanov-ai-dev/badge.svg)](/listings/pavel-molyanov--molyanov-ai-dev)

HTML

<a href="/listings/pavel-molyanov--molyanov-ai-dev"><img src="/api/listings/pavel-molyanov--molyanov-ai-dev/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Clone the repository:

git clone https://github.com/pavel-molyanov/molyanov-ai-dev.git
cd molyanov-ai-dev

For a new or empty setup, copy the runtime you use:

mkdir -p ~/.claude/scripts ~/.codex
cp -R skills agents ~/.claude/
cp scripts/sync-*.py scripts/sync-*.sh ~/.claude/scripts/
cp -R .codex/skills .codex/agents ~/.codex/

If you already use Claude Code or Codex, do not overwrite your whole configuration. Compare this repository's `CLAUDE.md` and `AGENTS.md` with your files and manually add the instructions you are missing. Update framework skills and agents selectively, remove only obsolete framework packages, and keep your personal packages and Codex-owned `.codex/skills/.system` unchanged.

Then describe the outcome in plain language. Skills route by intent; slash-command wrappers are not required.

Typical starting points:

- New repository: “Initialize this project” → `project-initialization` - Initial or updated project documentation: “Create Project Knowledge” → `documentation-writing` - Feature that needs agreement first: “Let's plan this feature” → `user-spec-planning` - Small implementation: “Implement/fix this” → the matching execution skill - Review only: “Review this code/layout/security boundary” → the matching review skill

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 218 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. **English** | [Русский](README.ru.md)
  2. # AI-First Development Framework
  3. **Telegram:** [@molyanov_blog](https://t.me/molyanov_blog)
  4. A practical, intent-driven methodology for building software with
  5. [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and
  6. [Codex](https://github.com/openai/codex). It combines proportional planning, durable Project
  7. Knowledge, focused execution skills, and evidence-gated review without forcing every task through
  8. the same heavyweight pipeline.
  9. User-facing artifacts follow the user's language. Technical documentation, code, prompts, and
  10. skill instructions stay in English so the same project remains portable across sessions and
  11. runtimes.
  12. ## Two runtimes, one source
  13. Claude files are the editable source of truth. Codex files are generated runtime artifacts.
  14. | Claude source | Codex runtime |
  15. |---|---|
  16. | `~/.claude/skills/**` | `~/.codex/skills/**` |
  17. | `~/.claude/agents/*.md` | `~/.codex/agents/*.toml` |
  18. | `~/.claude/commands/*.md`, when present | `~/.codex/skills/source-command-*/**` |
  19. | Project `CLAUDE.md` | Project `AGENTS.md` |
  20. | Project `.claude/skills/**` and `.claude/commands/*.md` | Project `.agents/skills/**` |
  21. | Project `.claude/agents/*.md` | Project `.codex/agents/*.toml` |
  22. After editing Claude-side sources, regenerate and review the Codex runtime:
  23. ```bash
  24. ~/.claude/scripts/sync-to-codex.sh --apply
  25. ~/.claude/scripts/sync-to-codex.sh --project "$PWD" --apply
  26. ```
  27. Run conversion after editing sources; project Git hooks also run it before commits and check
  28. for drift before pushes. The converter reports conflicts, validation failures, and managed orphans.
  29. On the next project sync it automatically moves its legacy `.codex/skills` into `.agents/skills`;
  30. unknown or manually edited files require conflict resolution.
  31. ## Quick start
  32. Clone the repository:
  33. ```bash
  34. git clone https://github.com/pavel-molyanov/molyanov-ai-dev.git
  35. cd molyanov-ai-dev
  36. ```
  37. For a new or empty setup, copy the runtime you use:
  38. ```bash
  39. mkdir -p ~/.claude/scripts ~/.codex/skills ~/.codex/agents ~/.agents
  40. cp -R skills agents ~/.claude/
  41. cp scripts/*.py scripts/*.sh ~/.claude/scripts/
  42. cp -R .agents/skills/. ~/.codex/skills/
  43. cp -R .codex/agents/. ~/.codex/agents/
  44. if [ ! -e ~/.agents/skills ] && [ ! -L ~/.agents/skills ]; then
  45. ln -s ../.codex/skills ~/.agents/skills
  46. fi
  47. ```
  48. If you already use Claude Code or Codex, do not overwrite your whole configuration. Compare this
  49. repository's `CLAUDE.md` and `AGENTS.md` with your files and manually add the instructions you are
  50. missing. Update framework skills and agents selectively, remove only obsolete framework packages,
  51. and keep your personal packages and Codex-owned `~/.codex/skills/.system` unchanged.
  52. Global skills physically live in `~/.codex/skills`, and agents in `~/.codex/agents`. Codex
  53. discovers skills through the `~/.agents/skills` → `../.codex/skills` symlink; published agents
  54. reference files in `~/.codex/skills`. If `~/.agents/skills` already exists, verify that it is the
  55. correct symlink. Reconcile its contents first if it is a real directory; do not copy a second
  56. skill set there. Use `unlink ~/.agents/skills` when replacing the symlink.
  57. Then describe the outcome in plain language. Skills route by intent; slash-command wrappers are
  58. not required.
  59. Typical starting points:
  60. - New repository: “Initialize this project” → `project-initialization`
  61. - Initial or updated project documentation: “Create Project Knowledge” → `documentation-writing`
  62. - Feature that needs agreement first: “Let's plan this feature” → `user-spec-planning`
  63. - Small implementation: “Implement/fix this” → the matching execution skill
  64. - Review only: “Review this code/layout/security boundary” → the matching review skill
  65. ## How the methodology works
  66. ### Choose the smallest path that fits
  67. | Need | Workflow |
  68. |---|---|
  69. | Small, well-defined change | Matching execution skill directly |
  70. | Feature whose behavior or approach needs agreement | `user-spec-planning` → approval → implementation → finalization |
  71. | New repository | `project-initialization` → initial Project Knowledge → feature or ad-hoc work |
  72. | Documentation-only work | `documentation-writing` with an explicit evidence boundary |
  73. | Review or audit only | Matching review skill or reviewer; no artifact modification |
  74. One request may activate several skills. A UI feature with state changes, for example, can combine
  75. `layout-writing` and `code-writing` while sharing one verification and review cycle.
  76. ### Planned feature lifecycle
  77. 1. **Plan.** `user-spec-planning` runs an adaptive interview, reads relevant Project Knowledge,
  78. researches the codebase, clarifies errors and edge cases, and writes
  79. `work/{feature}/user-spec.md` from bundled templates.
  80. 2. **Validate.** Fresh quality, adequacy, and factual-codebase reviewers check the same draft.
  81. Findings must identify concrete evidence, a violated requirement, realistic conditions, and
  82. impact.
  83. 3. **Approve.** The user explicitly approves the user spec before implementation begins.
  84. 4. **Implement.** The required execution skills make the scoped change and run the smallest checks
  85. that establish the result. Applicable reviewers inspect the completed revision. Findings are
  86. presented to the user; fixes and another review require their approval.
  87. 5. **Finalize.** `documentation-writing` updates only affected durable Project Knowledge and moves
  88. the feature folder to `work/completed/{feature}/`.
  89. A small direct request does not need a user spec. Risks or ideas found during execution are
  90. reported as proposals; they do not silently expand the authorized scope.
  91. ### Project Knowledge
  92. Durable project facts live in `.claude/skills/project-knowledge/`. Its `SKILL.md` is the router and
  93. loads only the context needed for the current task. Standard projects may use references such as:
  94. - `project.md` — purpose, audience, features, and scope
  95. - `architecture.md` — stack, structure, integrations, and data boundaries
  96. - `patterns.md` — project-specific conventions, testing, and business rules
  97. - `deployment.md` — environments, delivery, operations, and recovery
  98. - `ux-guidelines.md` — UX language and domain guidance when it forms a useful context boundary
  99. `CLAUDE.md` stays a compact entry point rather than duplicating this documentation.
  100. ## Skills
  101. ### Planning and project context
  102. | Skill | Purpose |
  103. |---|---|
  104. | `methodology` | Explains routing, lifecycle, sources of truth, and review model |
  105. | `project-initialization` | Creates a dual-runtime project with hooks and a private GitHub repository: `main` + `dev` for software, `main` only for a skills workspace; preserves existing files |
  106. | `documentation-writing` | Creates, audits, updates, and finalizes Project Knowledge |
  107. | `user-spec-planning` | Produces an approved user spec through adaptive interview, code research, and validation |
  108. ### Execution
  109. | Skill | Purpose |
  110. |---|---|
  111. | `code-writing` | Application behavior, APIs, state, validation, and focused code changes |
  112. | `layout-writing` | High-fidelity UI implementation, responsive behavior, and visual evidence |
  113. | `infrastructure-setup` | Local setup, Docker, hooks, CI/CD, delivery, monitoring, backups, and operations |
  114. | `prompt-master` | LLM prompt creation, improvement, and review |
  115. | `skill-master` | Skill and reviewer-agent creation or revision |
  116. ### Testing and review
  117. | Skill | Purpose |
  118. |---|---|
  119. | `test-master` | Selects the smallest reliable test boundary for deterministic behavior and reviews test quality |
  120. | `code-reviewing` | Reviews code against scope, project contracts, and quality risks |
  121. | `layout-reviewing` | Reviews visual fidelity, responsiveness, and evidence coverage |
  122. | `security-auditor` | Reviews changed security boundaries against applicable OWASP risks |
  123. ## Agents
  124. Agents provide fresh, bounded context for research and skeptical review. Reviewers diagnose only:
  125. they do not edit artifacts or decide whether work ships.
  126. | Group | Agents |
  127. |---|---|
  128. | Research and user-spec validation | `code-researcher`, `interview-completeness-checker`, `skeptic`, `userspec-quality-validator`, `userspec-adequacy-validator` |
  129. | Implementation and documentation review | `code-reviewer`, `layout-reviewer`, `test-reviewer`, `security-auditor`, `documentation-reviewer`, `infrastructure-reviewer`, `prompt-reviewer` |
  130. | Skill review | `skill-checker`, `skill-logic-reviewer`, `skill-simplicity-reviewer` |
  131. Claude definitions live in `agents/*.md`; native Codex definitions live in
  132. `.codex/agents/*.toml`.
  133. ## Bundled skill resources
  134. Resources now live with the skill that owns them; the legacy shared resource tree has been
  135. removed.
  136. - `project-initialization/assets/new-project/` — dual-runtime project scaffold, Project Knowledge,
  137. hooks, secret-safe `.gitignore`, backlog, and work archive
  138. - `user-spec-planning/assets/` and `scripts/` — user-spec, interview, decisions templates, and
  139. deterministic feature-folder initialization
  140. - `documentation-writing/assets/` and `references/` — Project Knowledge interview and topology
  141. guidance
  142. - `layout-writing/scripts/` — capture, overlay, and visual comparison utilities with tests
  143. - `infrastructure-setup/references/` — deployment, release, monitoring, and alerting guidance
  144. - `test-master/references/` — unit, integration, smoke, end-to-end, and test-review guidance
  145. - `skill-master/references/` — skill forms, interviews, reviewer contracts, and output patterns
  146. ## Scripts and Codex support
  147. - `scripts/sync-to-codex.py` / `.sh` convert Claude skills, agents, commands, and project
  148. instructions into Codex runtime artifacts.
  149. - `scripts/sync-mcp-to-codex.py` / `.sh` preview and import MCP configuration separately from skill
  150. conversion.
  151. - `scripts/codex-sync-git-guard.py` synchronizes project sources before commits and checks runtime
  152. drift before pushes.
  153. - `.agents/skills/` and `.codex/agents/` provide a ready-made sanitized Codex runtime snapshot.
  154. - Root `.githooks/` maintain this public snapshot from `skills/` and `agents/`;
  155. `.githooks/sync-runtime.py --check` checks it without writing.
  156. - Codex-owned `.system` skills and host-local `.codex/.sync/` state are intentionally excluded.
  157. ## Requirements
  158. - Claude Code CLI and/or Codex CLI
  159. - Python 3.11+
  160. - Bash-compatible shell (macOS/Linux, WSL, or Git Bash on Windows)
  161. - Git; GitHub CLI (`gh`) for `project-initialization`
  162. - Context7 MCP configuration used by the bundled project template
  163. - Node.js when using the bundled layout capture and comparison scripts
  164. ## License and author
  165. [MIT](LICENSE) © [Pavel Molyanov](https://molyanov.ru)
  166. **Telegram:** [@molyanov_blog](https://t.me/molyanov_blog)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.