# Workflow Iniciar Aplicacao

> Iniciar aplicação, CLI, serviço, ferramenta ou módulo novo com organização mínima de pastas, OU estender projeto existente com bounded context novo. Use quando o usuário pedir para criar/iniciar/adicionar app/CLI/utilitário/módulo/biblioteca/serviço/funcionalidade, especialmente sem stack definida. Palavras-gatilho: "crie", "inicie", "adicione", "novo módulo", "novo serviço", "extraia BC", "bound…

- **Type:** Skill
- **Install:** `agentstack add skill-gianverdum-ai-dev-skillset-workflow-iniciar-aplicacao`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [gianverdum](https://agentstack.voostack.com/s/gianverdum)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [gianverdum](https://github.com/gianverdum)
- **Source:** https://github.com/gianverdum/ai-dev-skillset/tree/main/.agents/skills/workflow-iniciar-aplicacao

## Install

```sh
agentstack add skill-gianverdum-ai-dev-skillset-workflow-iniciar-aplicacao
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Iniciar Aplicação

Use esta skill quando o pedido criar software novo ou uma funcionalidade sem estrutura existente clara.

## Decisões Iniciais

1. Leia a estrutura existente antes de criar arquivos.
2. Se houver padrão claro no projeto, use esse padrão e informe a suposição.
3. Quando criar ou reorganizar estrutura, nomes de arquivos, pacotes, módulos, classes, funções ou testes, consulte a rule da linguagem em `.agents/rules`.
4. Se a linguagem não estiver explícita e o pedido for uma CLI, utilitário local ou ferramenta pequena sem requisito de stack, use Python com `uv` como padrão e informe a suposição.
5. Se a linguagem, runtime ou framework não estiverem explícitos e a escolha afetar arquitetura, deploy, UI, integração externa ou custo relevante, pergunte antes de implementar.
6. Se o pedido for pequeno, ainda trate como módulo evolutivo quando a skill de arquitetura estiver ativa.

## Escopo do Projeto

- Trate a raiz do repositório como a raiz do projeto. Manifesto (`pyproject.toml`, `package.json`, `pom.xml`, `Cargo.toml`, `go.mod`, `.sln`/`.csproj`, etc.), `src/`, `tests/`, `README.md`, `.gitignore` e lockfile ficam na raiz do repositório.
- Não crie uma pasta intermediária com o nome do projeto na raiz do repo para depois colocar `src/` dentro dela. Layout errado: `/calculadora/src/calculadora/...`. Layout correto: `/src/calculadora/...`.
- O nome do módulo aparece apenas dentro de `src/` (e em manifestos como `[project] name` ou `package.json` `name`), não como diretório irmão de `src/`.
- Exceção: monorepo explícito com mais de um deliverable independente. Nesse caso, cada projeto fica em `apps//`, `packages//` ou `services//`, mantendo seu próprio manifesto e `src/` interno. Só adote esse layout quando já existir mais de um projeto no repositório ou o usuário pedir explicitamente; não crie monorepo preventivamente para abrigar um único projeto.
- Se o repositório já tiver convenção diferente (ex.: várias pastas-projeto no topo), preserve-a e informe a suposição.

## Quando Criar Modulo Separado vs Submodulo de Camada

Modulo = bounded context (DDD). Camada/adapter dentro de um modulo NAO e modulo separado.

**Vale tanto na criacao inicial quanto em qualquer extensao** (adicionar feature/funcionalidade nova num projeto existente). Ao estender, reaplique os criterios abaixo SEMPRE — nao caia em "preservar o padrao local" por inercia quando a feature nova introduz vocabulario, ciclo de vida ou regra com identidade propria. "Preservar padrao local" vale para conveções de naming/estilo/layout, nao para misturar bounded contexts no mesmo modulo.

Crie modulo SEPARADO quando ao menos um destes for verdade:

- O vocabulario/linguagem ubiqua e diferente (`task` x `project`, `payment` x `notification`, `inventory` x `pricing`).
- O ciclo de vida das regras e independente (mudam por motivos diferentes, em ritmos diferentes).
- Modelos com mesmo nome tem significados distintos (um `User` em `auth` e diferente do `User` em `billing`).
- Existe possibilidade real e prevista de extrair o modulo como servico/biblioteca separada.

NAO crie modulo separado para o que e claramente parte do mesmo bounded context:

- Adapter de persistencia da entidade do proprio modulo (`task-storage`, `task-repository`, `task-db`). Isso e submodulo de infraestrutura/adapter, NAO modulo irmao.
- Cliente HTTP que serve o nucleo do modulo (`payment-api-client` e adapter de saida de `payment`).
- Utilitarios, helpers, value objects, mappers.
- Camadas tecnicas (controllers, handlers, repositories, schemas).

### Sintomas de vazamento de bounded context (DESVIO)

Quando uma extensao precisaria ser modulo novo mas foi enxertada no existente, normalmente aparecem estes sintomas. Cada um sozinho ja sinaliza problema:

- Tipo de uma entidade existente ganhou campos com vocabulario do novo dominio (ex.: `Task.completedBillingMonth`, `User.subscriptionTier`, `Order.crmContactId`).
- O `State`/agregado do modulo existente ganhou novo campo com colecao do novo dominio (ex.: `ProjectManagementState.monthlyCharges`, `ShopState.shippingLabels`).
- Constantes/regras com vocabulario do novo dominio aparecem em arquivos do dominio existente (ex.: `COMPLETED_TASK_CHARGE_CENTS` em `domain/project.ts`).
- A policy table do modulo existente ganhou actions do novo dominio (`issue_monthly_charges`, `print_shipping_label`).
- Parametros de comando da UX existente passam a exigir campos do novo dominio (ex.: `complete-task --billing-month 2026-06`).
- README do modulo existente passa a citar dominios novos no titulo/responsabilidade ("gerencia projetos, tasks **e cobrancas**", "gerencia pedidos **e envios**").

Quando 2+ desses sintomas estao presentes, extraia o novo dominio para `src//` e ligue por porta. Os campos/regras que vazaram para o modulo existente voltam a ser primitivos genericos (`Task.completedAt: Date`, `Task.completedBy: UserId`) e o novo modulo deriva os conceitos proprios a partir dai.

### Exemplos

**Errado** — `storage` como modulo irmao de `task`:

```
src/
  task/
    domain/
    application/
    interface/
  storage/                       # NAO e bounded context, e adapter de saida de task
    file-task-repository.ts
```

**Certo (Clean Arch)** — `storage` vive dentro de `task`:

```
src/
  task/
    domain/
    application/
    interface/
    infrastructure/
      file-task-repository.ts    # adapter de saida do proprio modulo
```

**Certo (Hexagonal)** — adapter de saida em `adapters/out/`:

```
src/
  task/
    domain/
    application/
      ports/task-repository.ts
      use-cases/add-task.ts
    adapters/
      in/cli/
      out/file-task-repository.ts
    config/
```

**Certo (multi-modulo real)** — dois bounded contexts distintos:

```
src/
  task/                          # gestao de tarefas
    domain/ application/ interface/ ...
  project/                       # gestao de projetos (linguagem propria)
    domain/ application/ interface/ ...
  # cada um com seu README; integracao via porta declarada no nucleo
```

Em duvida, comece com um modulo unico. Quebrar dois modulos juntos depois e barato; reverter uma quebra prematura e custoso.

## Organização Mínima

- Não crie arquivos soltos na raiz para código de produção, exceto manifests, configuração, documentação essencial ou entrypoints esperados pela stack.
- Na ausência de padrão local, aplique a rule de nomenclatura e estrutura da linguagem escolhida.
- Crie ou atualize o manifesto da stack quando a aplicação precisar de dependências, ferramentas de teste, comandos ou metadados de pacote.
- Instale e registre dependências no projeto, usando o gerenciador idiomático da stack; não dependa de pacotes globais ou instruções manuais quando o projeto puder declarar a dependência.
- Para Python, use sempre `uv`: inicialize `pyproject.toml` quando necessário, adicione dependências com `uv add` ou `uv add --dev`, execute comandos com `uv run` e mantenha `uv.lock` quando ele for gerado.
- Para Python novo, crie `pyproject.toml` com metadados mínimos, `requires-python`, entrypoint quando houver CLI, build backend simples e configuração das ferramentas usadas.
- Crie ou atualize `.gitignore` antes do primeiro commit. Esta é uma exigência obrigatória, não recomendação. Cubra no mínimo, por stack:
  - Python: `.venv/`, `.coverage`, `coverage.xml`, `htmlcov/`, `__pycache__/`, `*.pyc`, `.pytest_cache/`, `.ruff_cache/`, `.mypy_cache/`, `dist/`, `build/`, `*.egg-info/`.
  - JavaScript/TypeScript: `node_modules/`, `dist/`, `build/`, `.next/`, `.turbo/`, `coverage/`, `.cache/`, `.env*` exceto `.env.example`.
  - Java/Kotlin: `target/`, `build/`, `.gradle/`, `*.class`.
  - C#/.NET: `bin/`, `obj/`, `*.user`, `.vs/`.
  - Go: binários compilados na raiz, `vendor/` quando não versionado.
  - Rust: `target/`, `Cargo.lock` apenas em bibliotecas publicadas.
- Se algum desses artefatos já estiver versionado por engano, remova do índice (`git rm --cached`) ao adicionar a entrada no `.gitignore`.
- Coloque módulos, aplicações, CLIs, serviços e bibliotecas dentro do `src/` da raiz do repositório, criando `/src/` quando não houver padrão mais específico.
- Não crie diretórios de aplicação diretamente na raiz do repositório, como `calculator_cli/` ou `calculadora/`, salvo quando a stack exigir esse formato, o repositório for um monorepo explícito ou o padrão existente já use esse layout.
- Crie sempre as camadas minimas obrigatorias no modulo, conforme a skill de arquitetura ativa:
  - **Clean Architecture (default)**: `domain`, `aggregates`, `value-objects`, `application` e `interface`. Carregue `architecture-ddd-clean-arch`.
  - **Hexagonal**: `domain`, `aggregates`, `value-objects`, `application` e `adapters/in` + `adapters/out`. Carregue `architecture-ddd-hexagonal`.
  - Escolha por precedencia: (1) padrao do projeto existente; (2) solicitacao explicita do usuario; (3) default Clean Architecture.
- `aggregates/` e `value-objects/` ficam **no mesmo nivel de `domain/`** (irmaos), nao dentro de `domain/`. Cada aggregate root e cada VO em arquivo proprio.
- VOs de identidade compartilhados entre BCs ficam em `src/shared-kernel/value-objects/` na RAIZ de `src/`, NUNCA dentro de outro modulo.
- Bounded contexts separados sao **modulos irmaos em `src/`** (cada um com sua estrutura completa). Subpastas dentro de `domain/` com nomes de BC nao contam como BCs separados.
- Vale tambem para CLIs e utilitarios pequenos: a camada `application` (ou caso de uso ligado a porta de entrada, em Hexagonal) nao pode ser omitida por simplicidade aparente. A interface (ou `adapters/in`) chama o caso de uso, nunca o dominio direto.
- A colocacao dos testes unitarios e decidida pela rule da linguagem em `.agents/rules`, nao por preferencia global. Resumo das convencoes modernas: Go e Rust colocalizam unitarios junto ao codigo (Rust em modulo `#[cfg(test)]`); TypeScript e JavaScript preferem colocalizado (`foo.test.ts` ao lado de `foo.ts`); Python, Java, C# e PHP usam diretorio espelhado (`tests/` na raiz, `src/test/java`, projeto `*.Tests`, etc.). Siga sempre o padrao da rule da linguagem usada.
- Use `tests/` no mesmo nivel de `src/` para integracao, contrato, ponta a ponta, fixtures compartilhadas e suites que cruzam modulos, independentemente de onde ficam os unitarios.
- Tudo que entrar em `tests/` (unitarios em Python/PHP, integracao/contrato/e2e em qualquer linguagem) deve ser agrupado primeiro pelo TIPO em subpastas como `tests/unit/`, `tests/integration/`, `tests/contract/`, `tests/e2e/`, `tests/acceptance/`. Dentro de cada subpasta de tipo, espelhe a estrutura de `src/`: um teste de `src///` vira `tests////test_` (com o sufixo do framework). Excecoes: Java/Kotlin (sufixo `*Test`/`*IT` sobre `src/test/java`) e C#/.NET (projetos `*.UnitTests`/`*.IntegrationTests` separados) seguem a convencao da stack.
- Carregue e aplique a skill `documentation-modulos-projeto` sempre que criar ou reorganizar um projeto ou modulo. Crie, na mesma mudanca, o `README.md` da raiz do repositorio e um `README.md` proprio para cada modulo de aplicacao criado (o pacote principal dentro de `src/`, ou cada projeto em `apps//`, `packages//` ou `services//` em monorepo). Submodulos de camada como `domain`, `application`, `interface`, `adapters` ou equivalentes NAO recebem README proprio: sao descritos dentro do README do modulo. README de modulo nao e opcional: a tarefa so termina quando todo modulo novo tem o seu.
- Mantenha artefatos gerados, cache e build fora do versionamento quando aplicável.

## CLI

- Para uma CLI, crie um entrypoint claro e uma camada de interface responsável apenas por parsing, validação de entrada textual e apresentação de saída.
- Mantenha cálculo, decisão e regra de negócio fora do arquivo de CLI.
- Exponha comandos de execução e teste na resposta final.
- Para CLI Python, prefira entrypoint em `pyproject.toml` e documente execução por `uv run `; use `uv run python -m ` apenas quando um entrypoint ainda não fizer sentido.
- Em CLI Python, mantenha `__main__.py` apenas como glue fino para `python -m ` quando isso agregar compatibilidade; não coloque regra de negócio nele.

## Dependências e Ambiente

- Configure as ferramentas necessárias para cumprir os requisitos do pedido, incluindo teste, cobertura, lint ou build quando exigidos por outras skills.
- Carregue e aplique a skill `quality-lint-format`: todo projeto novo deve nascer com linter e formatter idiomaticos instalados, configurados e com scripts `lint` e `format` declarados no manifesto. O script `lint` invoca o linter real (nao alias de `typecheck` ou `build`). A escolha do linter por linguagem esta na rule da linguagem em `.agents/rules`.
- Antes de dizer que uma ferramenta não está instalada, tente adicioná-la ao projeto pelo gerenciador da stack e valide pelo comando do projeto.
- Não instale dependências de forma global, não use `pip install` direto em Python e não crie ambientes virtuais manualmente quando `uv` puder gerenciar o ambiente.
- Se uma instalação precisar de rede, permissão externa ou ferramenta ausente, solicite a aprovação necessária ou registre o bloqueio concreto na resposta final.

## Checklist

- A linguagem ou stack foi confirmada ou inferida por padrão existente.
- Em CLI/utilitário pequeno sem stack explícita, Python com `uv` foi usado como padrão ou outra escolha foi justificada.
- O manifesto da stack foi criado ou atualizado quando havia dependências, comandos ou ferramentas.
- Dependências necessárias foram adicionadas ao projeto pelo gerenciador correto; em Python, por `uv`.
- Linter e formatter idiomaticos foram instalados e configurados; scripts `lint` e `format` no manifesto invocam ferramentas reais, nao aliases.
- `.gitignore` cobre ambiente local, caches e artefatos gerados pela stack, conforme a lista mínima por linguagem.
- Nenhum dos artefatos listados (ex.: `.venv/`, `.coverage`, `node_modules/`, `target/`, `bin/`, `obj/`) está versionado.
- Código de produção não ficou espalhado na raiz.
- `src/`, `tests/` e manifesto estão na raiz do repositório, não dentro de uma pasta com o nome do projeto.
- A funcionalidade nasceu dentro de `/src/` com as camadas minimas exigidas pela skill de arquitetura ativa (Clean Arch: `domain`/`application`/`interface`; Hexagonal: `domain`/`application`/`adapters/in`+`adapters/out`).
- Modulos irmaos em `src/` representam BOUNDED CONTEXTS distintos. Persistencia, cliente HTTP, parser, mapper e demais adapters do proprio modulo NAO sao modulos irmaos — ficam como submodulo de camada dentro do modulo dono.
- A camada de entrada (interface ou `adapters/in`) delega para um caso de uso de `application`; nao chama o `domain` diretamente.
- A precedencia de arquitetura foi respeitada: padrao do projeto > pedido do usuario > default Clean Architecture.
- Testes unitários ficaram próximos do código ou no padrão da stack.
- Testes de integração e outros testes amplos ficaram em `tests/` no mesmo nível de `src/`.
- `README.md` da raiz do repositorio foi criado ou atualizado.
- Cada modulo de aplicacao criado tem o seu proprio `README.md`; submodulos de camada nao recebem README proprio.
- A skill `documentation-modulos-projeto` foi carregada e seu checklist foi cumprido.
- Rules aplicáveis de nomenclatura e estrutura foram consultadas quando não havia padrão local suficiente.
- A resposta final informa como executar e validar.
- A skill `quality-revisao-aderencia` foi rodada antes do resumo final e os desvios encontrados foram corrigidos.
- O resumo final inclui secao "Revisao de aderencia" com status ❌/✅ item-a-item da checklist objetiva. Frases de conclusao ("pronto", "concluido", "feito", "complete", "done") so foram usadas se ≤1 item vermelho.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [gianverdum](https://github.com/gianverdum)
- **Source:** [gianverdum/ai-dev-skillset](https://github.com/gianverdum/ai-dev-skillset)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-gianverdum-ai-dev-skillset-workflow-iniciar-aplicacao
- Seller: https://agentstack.voostack.com/s/gianverdum
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.