convez.ai
SkillDevOps & InfraestruturaIntermediário
paulinhps

AI Project Template SDD

paulinhps/project-ai-template

Estrutura SDD para governar e escalar projetos com assistentes de IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Template canônico para desenvolvimento dirigido por especificação (SDD) com skills de IA reutilizáveis, regras, agentes e padrões de governança. Padroniza projetos para Claude Code, Cursor, Codex e outros assistentes de IA, oferecendo estrutura de contexto compartilhado via `.ai` e overlays específicos por projeto.

Instalação

$npx convez-ai paulinhps/project-ai-template

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
2

Casos de uso

  • Bootstrap de projetos novos com contexto pré-configurado para IA
  • Compartilhamento de skills e regras operacionais entre múltiplos assistentes
  • Governança centralizada via `.ai` com customizações por projeto em `.ai-overlay`
  • Padronização de workflows entre Codex, Claude Code e Cursor

Veredito

Template sólido para equipes que usam múltiplos assistentes de IA e precisam de governança centralizada. Requer investimento inicial em setup (Git, Node.js, PowerShell) mas reduz fricção em projetos subsequentes através de estrutura canonizada.

README

A tradução para o português deste README ainda está na fila.

AI Project Context

.ai is the canonical source of truth for AI-assisted development in this repository. It stores the shared operating rules, skills, commands, agents, templates, MCP assets, canonical documentation, and prompt history used to start and maintain projects with AI.

Project-specific AI context belongs in .ai-overlay, which is versioned by the root repository. .ai-overlay mirrors .ai conceptually but starts with only README.md; create folders there only when project-specific rules, skills, commands, agents, templates, MCP assets, prompts, notes, or overrides are needed.

Root tool pointer paths should point to .ai, so changes made through activated tool paths affect the same underlying files. .agents is the shared agent pointer; .codex and .claude are activated only when the root is initialized for Codex, Claude Code, or both. On Windows, true symbolic links can require administrator privileges; directory junctions are the supported non-duplicating fallback.

AGENTS.md is the canonical shared root operating guide. Tool-specific entrypoints are generated only when required by the activated tool profile. Claude Code reads a root CLAUDE.md automatically but does not read AGENTS.md natively, so Claude activations keep a short CLAUDE.md bridge at the root that points to AGENTS.md and .ai. The bridge must not duplicate canonical content. Claude Code specifics, including how the .claude pointer interacts with Claude Code's own configuration, are documented in .ai/claude/overrides/claude-code.md. Codex specifics are documented in .ai/codex/overrides/codex.md.

Prerequisites

Before using this structure to initialize a new project from zero, install or confirm these tools:

  • Git, available as git in the terminal.
  • Node.js 20 LTS or newer and npm, available as node and npm.
  • PowerShell 7 or Windows PowerShell only when using the Windows-specific .ps1 setup path.
  • At least one AI coding tool that can read repository instructions, such as Codex and/or Claude.
  • Optional: administrator privileges on Windows if you want symbolic links instead of directory junctions.
  • Optional: a remote Git repository for .ai when the AI context should be shared across multiple projects as a submodule.
  • Optional: project-specific SDD/planning tools, configured only when explicitly requested for a project.

Tool Versions And Installation

ToolMinimumWindowsLinuxmacOSNotes
Git2.28+ preferredwinget install Git.GitUse the distro package managerbrew install gitgit init --initial-branch needs modern Git; scripts fall back to git branch -M main.
Node.js20 LTS+winget install OpenJS.NodeJS.LTSUse NodeSource, nvm, or the distro package managerbrew install node@20 or nvm install 20Required for the cross-platform setup script.
npmBundled with Node.jsBundled with Node.jsBundled with Node.jsBundled with Node.jsRequired by Node-based setup scripts and optional project tooling.
PowerShell7+ preferredBuilt-in Windows PowerShell works for the .ps1 path; PowerShell 7 recommendedInstall powershell only if using .ps1 scriptsInstall powershell only if using .ps1 scriptsOptional when using the Node setup script.

Git for Windows must include the standard Git Unix support files used by git submodule, including Git's bundled shell helpers. If git submodule status fails with missing utilities such as basename, sed, or git-sh-setup, repair or reinstall Git for Windows and prefer running Git from Git Bash, PowerShell 7, Windows Terminal, or another shell where the Git installation is complete.

Containerized Fallback

Projects using this context should prefer host setup when Git and Node.js are already available. When host parity is uncertain, add a project-specific DevContainer under the root .devcontainer/ directory. The reusable .ai context does not require Docker for normal operation, but a project DevContainer should provide at least Git, Node.js 20 LTS or newer, npm, and any project runtime such as .NET, Java, or Python.

Start a New Project from Zero

Use this sequence when creating a new repository that should adopt the shared AI structure.

The project initialization decision is: first place the shared .ai content in the project root, then ask an AI agent to execute the configuration skill. The skill owns root repository initialization, root files and directories, AI tool profile activation, .ai reference registration, and the initial root commit.

  1. Create or open the empty project directory. Do not run git init in the root manually.
mkdir my-project
cd my-project
  1. Clone or download the shared .ai context into the project root.

Use the shared AI repository when one exists:

git clone <AI_REPOSITORY_URL> .ai

For a local bootstrap, copy the prepared .ai directory into the project root:

cp -R <AI_CONTEXT_SOURCE> .ai

Windows PowerShell equivalent:

Copy-Item -Recurse <AI_CONTEXT_SOURCE> .ai
  1. Execute this prompt from the project root:
initialize project using .ai/skills/setup-ai-environment/SKILL.md skill

The skill is responsible for these root initialization tasks:

  • Initialize the root Git repository when it does not exist.
  • Create root directories and generated files such as docs/, sources/, .ai-overlay/README.md, AGENTS.md, tool bridges, and .gitignore.
  • Create .agents and activated tool links to .ai.
  • Register .ai as a submodule/gitlink only when .ai has a remote repository URL.
  • Ignore local-only .ai contexts in the root repository when .ai is copied manually or has no remote.
  • Create the initial root commit when the root repository has no commits.
  1. Run the cross-platform setup script when executing the skill manually.
node .ai/skills/setup-ai-environment/scripts/setup-ai-environment.mjs --ai-tool both

Windows PowerShell equivalent:

.\.ai\skills\setup-ai-environment\scripts\setup-ai-environment.ps1 -AiTool "both"

Use --ai-tool codex / -AiTool "codex" for a Codex-focused root, --ai-tool claude / -AiTool "claude" for a Claude-focused root, and both when both tool surfaces should be configured. both is the compatibility default.

  1. Confirm the expected root shape.
AGENTS.md
CLAUDE.md
.gitignore
.gitmodules
.ai/
.ai-overlay/
  README.md
.agents/     -> .ai
.codex/      -> .ai when Codex is activated
.claude/     -> .ai when Claude Code is activated
docs/
sources/
  1. Review the initialized project.
git status

The skill creates the initial root commit automatically when the root repository has no commits. Follow .ai/rules/conventional-commits.md for every later commit in the root repository and in the .ai repository.

Repository References

The root repository tracks reproducible references, not copied implementation trees.

  • Copied .ai directories without Git metadata are local-only and should be ignored from the root repository.
  • Local .ai Git repositories without origin are local bootstrap state; they may be ignored from the root repository or explicitly registered as local submodules.
  • Remote-backed .ai repositories should be registered as submodules using the remote URL.
  • Source projects under sources/ always become submodules: local repositories without origin use local URLs, and repositories with origin use remote URLs.

See .ai/rules/repository-submodule-references.md for the full rule.

How to Use the .ai Structure

Treat .ai as the project memory and operating system for AI-assisted work.

  1. Start every AI session by reading AGENTS.md from the project root.
  2. Use .ai/rules/ for shared rules that every agent must follow.
  3. Use .ai/skills/ for repeatable shared workflows and project setup tasks.
  4. Use .ai/commands/ for command definitions and slash-command assets that should be available across tools.
  5. Use .ai/agents/ for reusable agent definitions.
  6. Use .ai/templates/ for reusable specification, prompt, documentation, and workflow templates.
  7. Use .ai/docs/ for reusable documentation and decisions about the canonical AI context itself.
  8. Use .ai/mcp/ for shared MCP servers, configs, prompts, and skills.
  9. Use .ai/prompts/registry/ as the immutable audit trail of AI-driven project evolution.
  10. Load .ai-overlay/ after .ai when it exists. Treat it as the project-specific overlay.
  11. Put project-specific AI assets in .ai-overlay unless the user explicitly asks to evolve the canonical .ai context.
  12. Put shared behavior in shared folders first. Use .ai/codex/overrides/ or .ai/claude/overrides/ only for genuine shared tool-specific behavior.
  13. Never create independent activated tool pointer trees such as .codex, .claude, or .agents. Those paths must remain links to the canonical .ai assets.

Optional SDD Tooling

SDD and planning tools are project opt-ins, not part of the canonical setup path. Configure a specific tool only when the user explicitly asks for it. An OpenSpec propose -> apply -> archive flow is one such optional tool and is not wired by default; configure it only on explicit request.

When optional SDD tooling creates or requires rules, skills, commands, agents, templates, MCP assets, prompts, or overrides, register those assets under .ai-overlay so they stay project-specific. Use canonical .ai only when the user explicitly asks to evolve the shared context itself.

Shared Folders

  • rules/: shared AI rules and operating constraints.
  • skills/: shared skills for AI-assisted workflows.
  • commands/: shared command definitions and slash-command assets.
  • agents/: shared agent definitions.
  • templates/: shared templates for specs, prompts, docs, and workflows.
  • docs/: canonical documentation and ADRs about the reusable .ai context.
  • prompts/registry/: immutable, incrementally numbered prompt source files.
  • mcp/: shared MCP assets, including servers, configs, prompts, and skills.

Tool-Specific Overrides

  • codex/overrides/: Codex-specific behavior and local overrides.
  • claude/overrides/: Claude-specific behavior and local overrides.

Shared behavior should live in shared folders first. Use tool-specific override folders only when Codex and Claude need different behavior.

Project-specific overrides belong in .ai-overlay/codex/overrides/ or .ai-overlay/claude/overrides/ and should be created only when needed.

Tool Profiles

Setup-time tool activation is driven by profiles under:

skills/setup-ai-environment/assets/tool-profiles/

Each profile declares the tool id, display name, root entrypoint, canonical entrypoint, pointer path, override path, discovery summary, and personal-configuration guidance. Add future AI tools through skills/ai-agent-diagnostic/SKILL.md: the running agent must discover its own tool surface, fork the remote canonical repository, add the required profile and documentation, validate generated artifacts, and open a pull request back upstream. Prefer adding a profile and, when needed, extending the generic entrypoint template instead of hardcoding a new setup branch.

Prompt Registry

Prompt source files are immutable and versioned under .ai/prompts/registry.

Use this format:

####-prompt-name.md

Create the next registry file whenever a shared skill, rule, command, agent, template, MCP asset, setup convention, or seed file changes. The prompt registry is the audit trail of AI-driven project evolution.

Ver o original no GitHub

Bom para

Relacionados