pavel-molyanov/molyanov-ai-dev

# Code Reviewing

Function length, nesting, broad types, hardcoded values, repeated resource construction, or
multiple mocks are signals to investigate; they are not defects by themselves.

Within this lane, the reviewer may challenge correctness, complexity, architecture, or the chosen
approach and propose a useful simpler or stronger alternative. Ground findings and proposals in
the request, project evidence, or a concrete consequence; unsupported preference is not useful,
and a clean result is complete.

## Contents

- [Always Review](#always-review)
- [Review When Applicable](#review-when-applicable)

# Code Writing

## Understand the Change

1. Extract the requested behavior and what done means from the request or user-spec. Resolve
   ambiguity from repository evidence; ask only when a substantive choice changes the result or
   scope.
2. Read repository instructions, affected code, its usages, and only the project documentation
   needed to change it safely. A localized edit needs local context; cross-cutting work needs its
   contracts, architecture, and relevant patterns.
3. For non-trivial work, read every source file that will change, find affected contracts and
   reusable code, and establish the smallest useful baseline check. Inspect generated, lock,
   snapshot, or other mechanical artifacts through their generator, relevant diff, and
   deterministic validation rather than an unhelpful full read.

# Documentation Management

Create and maintain `.claude/skills/project-knowledge/` from the evidence source the user named.

Outside Feature Finalization Mode, follow
[create-project-knowledge.md](references/create-project-knowledge.md) when the user starts or
continues initial documentation and either its interview is still in progress or Project Knowledge
is missing, still a template, or only partially filled. Apply
[project-knowledge-structures.md](references/project-knowledge-structures.md) for content ownership
and structure. After writing, run the manual sync and continue at Documentation Review.

When the user explicitly asks to reorganize existing Project Knowledge, apply
[project-knowledge-structures.md](references/project-knowledge-structures.md). Ordinary updates
preserve the filled structure already in use.

# Infrastructure Conventions

## Scope and Judgment

- Project Knowledge is required infrastructure context. If it is absent, stop and ask the user to
  create or fill it before continuing.
- The user's request defines which changes are authorized. A request to inspect, review, or assess
  current infrastructure authorizes diagnosis and recommendations, not implementation.
- Existing architecture and Project Knowledge are the current contract, not proof that the setup
  is good. Report demonstrated defects, unnecessary complexity, unsafe behavior, operational
  risks, and worthwhile improvements instead of silently accepting them.
- Do not implement an improvement outside the user's request merely because it is beneficial.
  Explain the evidence, impact, and proposed direction, then obtain agreement before changing it.
- Discuss the situation with the user when material information is missing or contradictory, an

# Layout Reviewing

Judge the supplied implementation and prepared evidence. You may challenge the visual approach,
responsive behavior, or treatment of states and propose a stronger alternative within the supplied
scope. Do not replace an intentional source value with personal taste.

## Review Basis

- Where an exact source exists, it controls defined geometry, spacing, color, typography, crop,
  effects, layering, content placement, and responsive states.
- Where no source exists, use repository rules, the same component in other states, neighboring
  UI, tokens, and established components as the review standard.
- For a partial source, keep these responsibilities separate. General design conventions do not
  override values the source defines intentionally.

# Layout Writing

Deliver a layout that matches its exact source where one exists, fills only genuinely unspecified
decisions from project evidence, and works at relevant widths in the existing codebase.

## Scope and Source

1. Read repository guidance, the affected component and styles, tokens, fonts, images, nearby
   components, and the relevant run or build command.
2. Classify the scope:
   - `selected area` — verify the changed element, component, or section with its nearest context;
   - `whole page` — build an ordered inventory of every major visual block from source metadata,
     node IDs, a DOM outline, or complete source-image segments, then verify every item.
3. With an exact source, apply [reproduce.md](references/reproduce.md) — source acquisition,

# AI-First Development Methodology

## Purpose

The methodology keeps project and feature work understandable across sessions while making the
process proportional to the task. Durable project facts live in Project Knowledge, an approved
user-spec is the contract for a planned feature, execution skills own their domain workflows, and
fresh reviewer agents diagnose completed work without taking decisions away from the orchestrator
or the user.

## Operating Model

Requests route directly to skills by intent. The global `commands/` source is currently empty;
feature planning, direct execution, initialization, documentation, and finalization do not depend

# Project Initialization

Initialize the project in the current working directory. Existing project files are preserved in
an `old*` directory for later review; do not merge them into the new scaffold during this workflow.

## Dual-Runtime Project Generation

The bundled template contains Claude project sources under `.claude/**`. Its Git hooks use the
installed `~/.claude/scripts/codex-sync-git-guard.py`: pre-commit generates and stages `AGENTS.md`,
`.agents/skills/**`, and `.codex/agents/**` after the sources are staged; pre-push checks for drift.
Host-local `.codex/.sync/**` is ignored. A reported conflict or validation error stops the action.

## 1. Check the Current Directory

# Project Knowledge

This skill provides access to project documentation that defines how this project works, how code should be written, and how features should be developed.

## When to use

Activate this skill when you need to:
- Understand project architecture, tech stack, and data model
- Learn coding patterns, git workflow, and testing approach
- Check deployment setup, monitoring, and operational procedures
- Apply UX guidelines and design system
- Make technical decisions aligned with project standards

## Core references

# Prompt Master

Treat a prompt as a clear task contract. Add information that changes the result; do not add a
technique merely because it is common in prompt-engineering guides.

## Prompt Essentials

A prompt should communicate the applicable parts of:

- the task and required result;
- context the model cannot infer but needs to perform the task correctly;
- real constraints and the reasons behind non-obvious requirements;
- criteria that distinguish an acceptable result;
- the response format when it matters to the user or a downstream system.

# Security Auditor

## Applicable Risks

Select risks from the actual trust boundaries and capabilities in the project:

- injection in queries, commands, templates, logs, and interpreters;
- XSS and context-appropriate output encoding;
- CSRF, CORS, and browser security headers;
- authentication, session handling, authorization, and privilege escalation;
- SSRF, path traversal, unsafe file handling, and external requests;
- secrets, sensitive data exposure, cryptography, and secure randomness;
- unsafe deserialization, software/data integrity, and CI/CD trust;
- denial of service, missing bounds, abuse controls, and rate limiting;

# Skill Creator

## Manual Claude-to-Codex Sync

Claude-side is the source of truth for the converter's allowlist: global `CLAUDE.md`, `skills/**`,
`agents/*.md`, and `commands/*.md`; or project `CLAUDE.md`, `.claude/skills/**`,
`.claude/agents/*.md`, and `.claude/commands/*.md`. Codex-side outputs are generated runtime. No
scheduled job performs this conversion. After editing an allowlisted source, the editing agent runs
the matching command immediately and reviews the generated result:

```bash
~/.claude/scripts/sync-to-codex.sh --apply                   # global ~/.claude/**
~/.claude/scripts/sync-to-codex.sh --project "$PWD" --apply  # project .claude/**
```

# Test Master

## Decide What to Protect

Tests protect observable behavior or another explicit contract that must survive change. Trace
each selected scenario to the user request, user-spec, or changed project contract.

Automated tests apply only to deterministic executable code; LLM-produced results and
presentation-only layout use agent, manual, or visual verification instead.

Freely editable copy, presentation-only markup or styles, constants that merely repeat their
source value, and framework behavior normally have no test subject. They become testable when an
explicit user, accessibility, legal, safety, protocol, or project requirement makes their
presence or semantics invariant. Test that contract at an observable boundary rather than

# User Spec Planning

Thorough adaptive interview → codebase research → completeness review → user-spec.md → three-lane
validation → user approval. Output: `work/{feature}/user-spec.md` with status `approved`.

## Interview Style

Conduct the interview in the language the user writes in. Be an engaged co-thinker: propose
solutions, challenge weak answers with concrete examples or code evidence, and keep interviewing
until the applicable requirements are understood.

- Ask 3–4 questions per batch and run as many batches as needed.
- Save every question and answer verbatim after each user response.
- Give one substantive challenge to a weak or unclear answer, then accept a supported answer and