Agentic Workflow Kit

Reusable Codex workflow kit for spec-driven development, agentic security, git hygiene, and safe publishing.

Quick Start

Create a new Next.js project with Bun and install the workflow kit:

bunx create-agentic-workflow-kit create my-app --template next --pm bun

Or use Bun's create flow after publishing the package:

bun create agentic-workflow-kit my-app --template next --pm bun

Install into an existing project:

bunx create-agentic-workflow-kit init .

What It Provides

• spec: plan atomic features with SDD before implementation.
• spec-writer: named specialist gate for feature scope and SDD quality.
• design-director: named specialist gate for UI/UX, visual craft, and motion.
• feature-architect: named specialist gate for technical plans and module boundaries.
• git-manager: named specialist gate for branch, staging, commit, push, PR/MR, tag, and release decisions.
• implement: build from approved SDD docs with checks and commits.
• modify: change documented features while keeping docs and code synchronized.
• security-review: review app, privacy, dependency, and agentic security risks.
• spec-ship: close a confirmed daily branch into dev, then version/publish only after explicit approval.
• agentic-init: install or update this workflow kit in another repository.
• Project-scoped .codex/ runtime config with native read-only specialist agents, Plan mode reasoning tuning, and documented hooks/rules extension points.
• Codex best-practice standards for code review, external context/MCP usage, workflow retrospectives, and automation candidates.
• Agent Run Gate, development-plan workflow, feature evidence docs, and compliance scripts that fail closed before edit/commit/publish steps.
• Cloud-first collaboration policy for projects with authenticated task/document/knowledge MCPs: consult the knowledge/brain system first for daily planning and decisions, read Sidera Knowledge before local docs for product/plan/design, fall back to live task/document state only when today's relevant context is missing, and keep team-visible specs, bitacoras, planning notes, handoffs, and durable project docs external-first.
• Cloud Closure Gate for substantial work: when Sidera or another task/document MCP is available, start from the mapped issue/task, move it to progress when implementation begins, update that issue with the work log, relevant doc links/updates, and external IDs or a blocked reason.
• Sidera issue scope is current-cycle only by default. The kit should not scan, prioritize, move, or update backlog/global issues unless the user explicitly asks for backlog triage.
• Sidera workflow status policy: mapped tasks stay in progress until the user confirms review handoff; developers move them only to review (in_review / en revision) after confirmation. Final done / completed closure requires explicit user or owner approval.
• Sidera Plan de trabajo (spec_plan) is the cloud development plan for Sidera-backed projects. Read/create/update it before treating local docs/development-plan.md as canonical. It is historical and cumulative, not a daily-only plan: preserve previous phases, completed work, decisions, blockers, and changelog history while updating the current state. It must follow the same development-plan section contract and must not contain AGENTS/system/skill/source-order/git workflow rules. If it exists but is empty, malformed, or rewritten as only today's plan, repair it into the correct structure or ask for approval before substantial product work.
• Sidera design Knowledge (design_general, design_principles, design_tokens, design_components, design_image_style) is the cloud design source for Sidera-backed projects. Use local docs/design.md only as fallback or mirror.
• Sidera Knowledge update policy: mapped issues hold punctual implementation logs; Knowledge is updated when work changes reusable product, roadmap, design, architecture, security, platform, workflow, or incident-learning truth.
• Feed/bitacora is a fallback or incident/learning channel. When a mapped issue exists, the issue is the primary work log. The kit must not create backlog issues/tasks just to log status unless the user explicitly asks for a new task.
• Sidera-first SDD/evidence workflow: feature specs, QA notes, implementation summaries, reference links, and handoffs live in Sidera when the project has Sidera configured. docs/feature-<slug>/ is only an offline/local fallback or an explicit repo audit packet.
• Durable UI implementation artifacts are local only when the user requests files/screenshots or the project already supports them; otherwise Sidera issue/docs hold the work evidence.
• shadcn-first design-system bootstrap for Next.js + Tailwind projects after docs/brief.md and docs/design.md exist.
• Daily branch workflow: dev is integration, active work uses wip/daily-YYYY-MM-DD, and merge/version/publish actions require user confirmation.
• Human-owned visual QA for browser-reachable UI. The agent prepares measurable visual criteria and optional artifacts, but does not mark visual QA complete without user/developer confirmation.
• Tailwind-only component styling and Motion-first animation choreography rules for UI work.
• lucide-react as the default functional iconography system for React/Next.js UI work.
• Next.js architecture compliance for App Router boundaries, clean architecture feature modules, shared component naming, and GitLab MR handoff honesty.

Install Into A Project

From the target project root:

bunx create-agentic-workflow-kit init .

Or with the PowerShell installer:

powershell -NoProfile -ExecutionPolicy Bypass -File path\to\agentic-workflow-kit\scripts\Install-AgenticWorkflow.ps1 -TargetPath .

The installer adds:

• .agents/skills/
• .codex/
• AGENTS.md
• CLAUDE.md
• docs/standards/design-system.md
• docs/standards/design-compliance.md
• docs/standards/feature-modules.md
• docs/standards/server-actions.md
• docs/standards/code-review.md
• docs/standards/codex-workflow.md
• docs/standards/external-context.md
• docs/standards/automation-candidates.md
• For Next.js projects, neutral architecture anchors:
  • src/components/README.md
  • src/lib/README.md
  • src/lib/decorators/retry.ts
  • src/lib/decorators/timeout.ts
  • src/lib/decorators/types.ts
  • src/lib/logger.ts
  • src/lib/query-executor.ts
  • src/lib/result.ts
  • src/lib/safe-action.ts
  • src/lib/utils.ts
  • src/features/README.md

It does not overwrite existing files unless you pass -Force.

For Next.js projects, the scaffold also declares next-safe-action, zod, pino, pino-pretty, clsx, and tailwind-merge in package.json when they are missing, because src/lib/safe-action.ts, src/lib/logger.ts, src/lib/utils.ts, and the feature-module standards rely on them.

The .codex/ layer is intentionally separate from .agents/skills/. Skills hold reusable workflows; .codex/config.toml tunes the project runtime, and .codex/agents/*.toml defines native read-only Codex specialists for spec_writer, design_director, feature_architect, and git_manager. Hooks and rules are documented but inactive by default.

The installer does not create docs/development-plan.md. It installs a pending docs/standards/design-system.md scaffold. After installation, the user provides docs/brief.md and docs/design.md; then an agent creates docs/development-plan.md, completes the design-system baseline from those source documents, and adjusts AGENTS.md. The kit does not fabricate product truth or project-level visual direction.

The agent-created plan follows the v2 template: Agent Control Block, Inputs Reviewed, Build Strategy, Development Phases, Execution Plan, Parallel Work, Open Decisions, Agent Handoff, and Change Log. The agent must fill those sections from real project context and keep the YAML state synchronized with the control block.

Recommended first flow:

bun create agentic-workflow-kit my-app --template next --pm bun
cd my-app
agentic-workflow-kit doctor .

Then the user creates these two source documents:

docs/brief.md
docs/design.md

Then open Codex in the project and send this chat prompt:

Usa $agentic-init para finalizar el bootstrap del proyecto. Usa dev como integracion y pideme confirmacion antes de crear una rama diaria wip/daily-YYYY-MM-DD. Lee brief/design cloud o local, crea/actualiza Plan de trabajo, configura el sistema de diseno shadcn/Tailwind en docs/standards/design-system.md y ajusta AGENTS.md con contexto real del proyecto. No implementes features todavia.

After that bootstrap is complete, start the first feature:

/spec first-atomic-feature

The user should not need to provide branch or file commands. Slash commands exist, but natural language can route to the same workflows: ok vamos, hazlo, implementa esto, trabajemos esta issue, or aplica el cambio should trigger the matching /spec, /implement, or /modify flow when intent is clear. /spec is not a one-time session step: each issue/capability needs exact SDD docs before implementation. After bootstrap, Codex must give one concrete next prompt from the development plan, such as Siguiente prompt recomendado: /spec user-onboarding-intake, not /spec <feature-slug> or a loose example. /spec <feature> owns SDD docs, checks, cloud closure, and local commits on the confirmed daily branch wip/daily-YYYY-MM-DD. Local commits are automatic for agent-owned changes; merge to dev, version bumps, tags, pushes, deploys, npm publishes, or package publications require separate confirmation. If Codex asks whether it may use subagents, answering si/yes is enough.

When a project configures authenticated knowledge and task/document MCPs, the knowledge/brain system is the first source for daily planning, priorities, history, and decisions. If it has no relevant update for the current local date, the task/document system becomes the live fallback for current tasks, documents, blockers, transcripts, and operational state. Sidera holds team-visible feature specs, QA notes, implementation summaries, reference links, and handoffs. Local docs/feature-* folders are not created by default; use them only as an offline fallback, user-requested repo audit packet, or when a technical artifact truly must live with the commit. Do not mirror full external documents into the repository.

Daily planning requests such as el brief de hoy, brief de hoy, que hago hoy, or continuemos must report source status. Codex should not present a brief built only from docs/development-plan.md, docs/brief.md, feature docs, or code inspection as the real daily brief. If Brain/knowledge and live fallback cannot be checked, the answer must be labelled as a reduced local fallback.

The exact prompt el brief de hoy is treated as a hard-stop daily planning request. A daily brief answer without Source status is invalid, and missing Sidera project_id is not permission to answer from local repo docs.

Brain/knowledge: checked is valid only when Codex names the exact brain source it queried, such as a GitHub brain repository path, a Brain MCP/tool result, or another explicitly configured brain source. Sidera documents, Sidera briefs, Sidera issues, local repo docs, and inferred project plans do not count as Brain by themselves; they must be reported as live fallback or reduced local fallback.

For Zeeers projects, the known Brain source is the private GitHub repository Zeeeers/brain-system on main. Sidera must not be inferred as Brain; it is the live task/document/transcript fallback and the system used to create or update docs, tasks, and bitacoras.

For daily planning in Zeeers projects, GitHub Brain must be attempted before Sidera. Codex should not list Sidera projects, search for a Sidera project_id, or read Sidera knowledge until it has checked or failed to access Zeeeers/brain-system.

If GitHub tools are not visible in the thread, Codex must try to discover the GitHub app/connector before using Sidera. If GitHub cannot be discovered or invoked, the brief should stop and ask the user to enable or attach GitHub instead of silently falling back to Sidera.

For UI, onboarding, sensitive data, or product-defining fields, /spec must still ask a human discovery checkpoint before writing final SDD docs. Visual references are optional, but the agent must ask whether they exist or whether it should proceed from the project design docs. When references are absent, the workflow still requires a reference-free excellence contract from docs/brief.md, docs/design.md, docs/standards/design-system.md, existing UI, and the feature goal.

When the user provides screenshots, logos, mockups, image files, Figma links, app examples, or brand references, /spec must register durable Sidera links/docs first. Only create docs/feature-<feature>/references/manifest.md when Sidera is unavailable, the user explicitly wants a repo audit packet, or local files are required by the commit. Evidence that only says "attached in chat" is not enough for future implementation.

For /modify requests that make an SDD ready for implementation, the same checkpoint is required. The evidence must say Human discovery source: explicit user reply; inferred answers from docs or subagents are not enough.

For /implement UI work, successful lint/build is not enough. The implementation must read the Sidera reference/spec source before coding when user references exist, prepare a human visual QA handoff for browser-reachable UI, and compare the result against Sidera design Knowledge plus linked references. Local references/manifest.md / evidence.md apply only in local fallback mode. Visual QA is complete only after user/developer confirmation.

For Next.js + Tailwind UI work, $agentic-init must initialize shadcn/ui, install the core primitive set under src/components/ui, define the human visual QA handoff, complete docs/standards/design-system.md, and adapt primitives to Sidera design Knowledge or local docs/design.md before feature UI work begins. shadcn is the base, not the fidelity ceiling.

UI components should use Tailwind CSS utilities and shadcn primitive variants. globals.css is limited to Tailwind/shadcn imports, tokens, base layers, and documented exceptions.

Use the motion package for actual UI animation choreography. CSS keyframes/manual animation rules require documented exceptions.

For UI iconography, use lucide-react. If the dependency is missing, the SDD plan must declare it before implementation; agents should not hand-roll SVG icon components for functional controls.

Generated project instructions tell agents to respond in Spanish by default unless the user asks for another language.

CLI

agentic-workflow-kit init [target]
agentic-workflow-kit create <project-name> --template next --pm bun
agentic-workflow-kit doctor [target]
agentic-workflow-kit repair [target]

The Next.js generator uses create-next-app with TypeScript, App Router, Tailwind CSS, src/, Turbopack, and the requested package manager. It passes --no-agents-md so the generated project uses this kit's AGENTS.md instead of the default one.

Validate The Kit

bun run test
bun run doctor
bun run version:check

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\Test-AgenticWorkflowKit.ps1 -PluginPath .

Repair An Existing Installation

For repositories installed with an older kit version, run:

agentic-workflow-kit doctor .
agentic-workflow-kit repair .
agentic-workflow-kit doctor .

Or use the shortcut:

agentic-workflow-kit doctor . --fix

repair installs missing workflow files, scripts, standards, and Next.js architecture baseline files without overwriting existing files. Use --force only when you intentionally want to regenerate existing workflow files. It does not create docs/development-plan.md; that still belongs to the post-context bootstrap after user-provided docs/brief.md and docs/design.md exist.

Daily brief and GitHub Brain behavior lives in AGENTS.md and docs/standards/external-context.md. In existing projects, repair will skip those files unless --force is used. To update source-order behavior such as Zeeeers/brain-system before Sidera, review local customizations and run:

agentic-workflow-kit repair . --force

Versioning

The npm package and Codex plugin manifest share the same SemVer version. Check them with:

bun run version:check

Bump both files together with:

bun run version:bump -- patch

Use major, minor, patch, or an explicit version such as 0.2.0-alpha.0. Update CHANGELOG.md before publishing. See VERSIONING.md for the release policy.

Project Model

Keep this repository as the source of truth for the reusable workflow. Each product repository should keep its own generated AGENTS.md, .codex/, and installed .agents/skills/, customized for that project's stack, domain, security posture, and git rules.