@jaimevalasek/aioson 1.3.0

package/template/.aioson/skills/static/web3-solana-patterns.md

@@ -0,0 +1,324 @@
+# Web3 Solana Patterns
+
+> Anchor framework, PDAs, and account model. Rust programs that don't leak lamports.
+
+---
+
+## Solana account model — understand before coding
+
+Unlike Ethereum where contract storage is internal, **Solana programs are stateless**. All state lives in separate accounts that the program owns.
+
+```
+Program Account   → executable code (your Anchor program)
+Data Account      → state storage (owned by the program)
+Signer Account    → user wallet (signs transactions)
+System Account    → system program (creates accounts, transfers SOL)
+Token Account     → holds SPL tokens (owned by Token Program)
+```
+
+**PDA (Program Derived Address):** A deterministic account address derived from seeds + program ID. No private key — only the program can sign for it.
+
+---
+
+## Anchor program structure
+
+```
+programs/
+  my-program/
+    src/
+      lib.rs              ← entry point, declare_id!, mod declarations
+      instructions/
+        initialize.rs     ← one file per instruction
+        deposit.rs
+        withdraw.rs
+      state/
+        pool.rs           ← account data structures
+        config.rs
+      errors.rs           ← custom error codes
+      constants.rs        ← seeds, limits, fees
+    Cargo.toml
+tests/
+  my-program.ts          ← Anchor TypeScript tests
+Anchor.toml
+```
+
+---
+
+## Account data structures
+
+```rust
+// state/pool.rs
+use anchor_lang::prelude::*;
+
+#[account]
+#[derive(Default)]
+pub struct Pool {
+    pub authority: Pubkey,    // 32
+    pub token_mint: Pubkey,   // 32
+    pub total_deposits: u64,  // 8
+    pub fee_bps: u16,         // 2
+    pub bump: u8,             // 1  ← always store the PDA bump
+    pub _padding: [u8; 5],   // 5  ← align to 8-byte boundary
+}
+
+impl Pool {
+    // Calculate space: discriminator (8) + fields
+    pub const LEN: usize = 8 + 32 + 32 + 8 + 2 + 1 + 5;
+}
+```
+
+---
+
+## Instructions with account validation
+
+```rust
+// instructions/initialize.rs
+use anchor_lang::prelude::*;
+use crate::{state::Pool, constants::POOL_SEED, errors::ProtocolError};
+
+#[derive(Accounts)]
+pub struct Initialize<'info> {
+    #[account(
+        init,
+        payer = authority,
+        space = Pool::LEN,
+        seeds = [POOL_SEED, token_mint.key().as_ref()],
+        bump
+    )]
+    pub pool: Account<'info, Pool>,
+
+    pub token_mint: Account<'info, anchor_spl::token::Mint>,
+
+    #[account(mut)]
+    pub authority: Signer<'info>,
+
+    pub system_program: Program<'info, System>,
+}
+
+pub fn handler(ctx: Context<Initialize>, fee_bps: u16) -> Result<()> {
+    require!(fee_bps <= 1_000, ProtocolError::FeeTooHigh);  // max 10%
+
+    let pool = &mut ctx.accounts.pool;
+    pool.authority    = ctx.accounts.authority.key();
+    pool.token_mint   = ctx.accounts.token_mint.key();
+    pool.fee_bps      = fee_bps;
+    pool.bump         = ctx.bumps.pool;  // store bump for future PDA signing
+
+    Ok(())
+}
+```
+
+---
+
+## PDA signing (CPI with PDA as signer)
+
+```rust
+// When the program needs to sign on behalf of a PDA
+pub fn withdraw(ctx: Context<Withdraw>, amount: u64) -> Result<()> {
+    let pool = &ctx.accounts.pool;
+    let token_mint_key = pool.token_mint.key();
+
+    // Seeds must match exactly what was used to derive the PDA
+    let seeds = &[
+        POOL_SEED,
+        token_mint_key.as_ref(),
+        &[pool.bump],
+    ];
+    let signer_seeds = &[&seeds[..]];
+
+    // CPI transfer signed by the pool PDA
+    anchor_spl::token::transfer(
+        CpiContext::new_with_signer(
+            ctx.accounts.token_program.to_account_info(),
+            anchor_spl::token::Transfer {
+                from:      ctx.accounts.pool_token_account.to_account_info(),
+                to:        ctx.accounts.user_token_account.to_account_info(),
+                authority: ctx.accounts.pool.to_account_info(),
+            },
+            signer_seeds,
+        ),
+        amount,
+    )?;
+
+    Ok(())
+}
+```
+
+---
+
+## Custom errors
+
+```rust
+// errors.rs
+use anchor_lang::prelude::*;
+
+#[error_code]
+pub enum ProtocolError {
+    #[msg("Fee exceeds maximum allowed (10%)")]
+    FeeTooHigh,
+
+    #[msg("Insufficient balance for withdrawal")]
+    InsufficientBalance,
+
+    #[msg("Pool is currently paused")]
+    PoolPaused,
+
+    #[msg("Unauthorized: only pool authority can perform this action")]
+    Unauthorized,
+
+    #[msg("Arithmetic overflow")]
+    Overflow,
+}
+```
+
+---
+
+## Security validations
+
+```rust
+// Always validate: ownership, signer, mint, amounts
+
+#[derive(Accounts)]
+pub struct Deposit<'info> {
+    #[account(
+        mut,
+        seeds = [POOL_SEED, pool.token_mint.as_ref()],
+        bump = pool.bump,                          // validates PDA derivation
+        has_one = token_mint,                      // mint must match pool's mint
+    )]
+    pub pool: Account<'info, Pool>,
+
+    #[account(
+        mut,
+        associated_token::mint = token_mint,
+        associated_token::authority = user,        // validates ownership
+    )]
+    pub user_token_account: Account<'info, TokenAccount>,
+
+    #[account(
+        mut,
+        associated_token::mint = token_mint,
+        associated_token::authority = pool,        // pool owns this account
+    )]
+    pub pool_token_account: Account<'info, TokenAccount>,
+
+    pub token_mint: Account<'info, Mint>,
+
+    pub user: Signer<'info>,                       // must sign the transaction
+    pub token_program: Program<'info, Token>,
+    pub associated_token_program: Program<'info, AssociatedToken>,
+    pub system_program: Program<'info, System>,
+}
+
+pub fn handler(ctx: Context<Deposit>, amount: u64) -> Result<()> {
+    require!(amount > 0, ProtocolError::InsufficientBalance);
+    require!(!ctx.accounts.pool.paused, ProtocolError::PoolPaused);
+
+    let pool = &mut ctx.accounts.pool;
+
+    // Safe arithmetic — use checked operations
+    pool.total_deposits = pool.total_deposits
+        .checked_add(amount)
+        .ok_or(ProtocolError::Overflow)?;
+
+    // ... transfer tokens
+    Ok(())
+}
+```
+
+---
+
+## Compute budget management
+
+```ts
+// client-side: add compute budget for complex instructions
+import { ComputeBudgetProgram } from '@solana/web3.js';
+
+const modifyComputeUnits = ComputeBudgetProgram.setComputeUnitLimit({
+    units: 400_000,  // increase from default 200k for complex CPI chains
+});
+
+const addPriorityFee = ComputeBudgetProgram.setComputeUnitPrice({
+    microLamports: 1_000,  // priority fee for faster inclusion
+});
+
+const tx = new Transaction()
+    .add(modifyComputeUnits)
+    .add(addPriorityFee)
+    .add(yourInstruction);
+```
+
+---
+
+## Anchor tests
+
+```ts
+import * as anchor from '@coral-xyz/anchor';
+import { Program } from '@coral-xyz/anchor';
+import { PublicKey, SystemProgram } from '@solana/web3.js';
+import { TOKEN_PROGRAM_ID, createMint, createAssociatedTokenAccount, mintTo } from '@solana/spl-token';
+import { MyProgram } from '../target/types/my_program';
+import { expect } from 'chai';
+
+describe('my-program', () => {
+    const provider = anchor.AnchorProvider.env();
+    anchor.setProvider(provider);
+    const program = anchor.workspace.MyProgram as Program<MyProgram>;
+
+    let tokenMint: PublicKey;
+    let [poolPda, poolBump]: [PublicKey, number];
+
+    before(async () => {
+        tokenMint = await createMint(provider.connection, provider.wallet.payer, provider.wallet.publicKey, null, 6);
+        [poolPda, poolBump] = PublicKey.findProgramAddressSync(
+            [Buffer.from('pool'), tokenMint.toBuffer()],
+            program.programId
+        );
+    });
+
+    it('initializes pool with correct state', async () => {
+        const feeBps = 300; // 3%
+
+        await program.methods
+            .initialize(feeBps)
+            .accounts({
+                pool:          poolPda,
+                tokenMint,
+                authority:     provider.wallet.publicKey,
+                systemProgram: SystemProgram.programId,
+            })
+            .rpc();
+
+        const pool = await program.account.pool.fetch(poolPda);
+        expect(pool.feeBps).to.equal(feeBps);
+        expect(pool.bump).to.equal(poolBump);
+        expect(pool.authority.toString()).to.equal(provider.wallet.publicKey.toString());
+    });
+
+    it('rejects fee above maximum', async () => {
+        try {
+            await program.methods.initialize(1_001).accounts({ ... }).rpc();
+            expect.fail('Should have thrown');
+        } catch (err: any) {
+            expect(err.error.errorCode.code).to.equal('FeeTooHigh');
+        }
+    });
+});
+```
+
+---
+
+## ALWAYS
+- Store PDA bump in the account and use it for future CPI signing
+- Use `has_one`, `constraint`, and `associated_token::authority` for account validation
+- Validate all amounts are > 0 before operations
+- Use `checked_add`, `checked_sub`, `checked_mul` — never plain arithmetic
+- Derive PDAs client-side with `PublicKey.findProgramAddressSync` and pass as account
+- One file per instruction in `instructions/`
+
+## NEVER
+- Trust user-provided account ownership — use Anchor constraints
+- Use unbounded loops (Solana has compute unit limits)
+- Skip PDA bump storage (you'll need it for CPI signing)
+- Mix up `lamports` (SOL × 10⁹) and token amounts (token × 10^decimals)
+- Deploy to mainnet without testing on devnet with realistic account sizes

package/template/.aioson/squads/memory.md

@@ -0,0 +1,5 @@
+# Squad Memory
+
+<!-- This file is initialized empty by aioson install.
+     @squad writes session notes here when the user chooses to persist memory.
+     Format is free — @squad manages it. -->

package/template/.aioson/tasks/squad-analyze.md

@@ -0,0 +1,83 @@
+# Task: Squad Analyze
+
+> Diagnostica um squad existente: cobertura, redundâncias, gaps, oportunidades.
+
+## Quando usar
+- `@squad analyze <slug>`
+- Quando o usuário quer melhorar um squad existente
+
+## Entrada
+- slug do squad existente
+
+## Processo
+
+### Passo 1 — Inventário de componentes
+Leia o squad.manifest.json e o filesystem real. Monte um inventário:
+- Executores: quantos, quais, com/sem skills, com/sem genomes
+- Skills: declaradas vs. instaladas em skills/
+- Content blueprints: quantos, com/sem sections
+- Templates: existem em templates/?
+- Docs: design-doc.md existe? readiness.md existe?
+- Output: há sessões HTML geradas?
+
+### Passo 2 — Métricas de cobertura
+Calcule:
+- % de executores com skills declaradas
+- % de executores com genomes
+- % de content blueprints com sections completas
+- % de docs presentes (design-doc, readiness)
+- Consistency score: manifest vs filesystem (arquivos referenciados que existem)
+
+### Passo 3 — Diagnóstico de problemas
+Identifique:
+- Sobreposição de responsabilidades entre executores (roles muito parecidos)
+- Skills faltantes (executor sem nenhuma skill)
+- Blueprints genéricos demais (sem sections ou com sections vazias)
+- Readiness fraco (dimensões blocked ou partial)
+- Excesso de complexidade (mais de 6 executores sem justificativa)
+- Arquivos órfãos (existem no filesystem mas não no manifesto)
+- Referências quebradas (no manifesto mas não no filesystem)
+
+### Passo 4 — Sugestões priorizadas
+Gere sugestões com prioridade (high/medium/low):
+- high: referências quebradas, manifest inconsistente, executor sem role
+- medium: skills faltantes, blueprints incompletos, docs ausentes
+- low: readiness parcial, genomes não aplicados, output vazio
+
+### Passo 5 — Relatório
+Apresente com este formato:
+
+```
+═══ Squad Analysis: <slug> ═══
+
+Overview
+  Name: <name>  |  Mode: <mode>  |  Version: <version>
+
+Components
+  Executors:   <n> (<n> with skills, <n> with genomes)
+  Skills:      <n> declared, <n> installed
+  Blueprints:  <n> (<n> complete)
+  Docs:        <status>
+
+Coverage
+  Skills:    ████░░░░░░ 40%
+  Genomes:   ██████░░░░ 60%
+  Docs:      ████████░░ 80%
+  Manifest:  ██████████ 100%
+
+Suggestions (<n>)
+  🔴 <high priority item>
+  🟡 <medium priority item>
+  🟢 <low priority item>
+
+Next: @squad extend <slug> to address suggestions
+```
+
+## Saída
+- Relatório no chat
+- Se --format markdown: salvar em .aioson/squads/<slug>/docs/ANALYSIS.md
+- Se --format json: saída JSON parseable
+
+## Regras
+- NÃO modifique nada — apenas diagnostique e recomende
+- SEMPRE sugira o próximo comando concreto para cada problema

package/template/.aioson/tasks/squad-create.md

@@ -0,0 +1,99 @@
+# Task: Squad Create
+
+> Fase de criação do lifecycle. Gera o pacote completo a partir de um blueprint.
+
+## Quando usar
+- `@squad create <slug>` — invocação direta
+- Automaticamente após `@squad design` ser aprovado
+- `@squad` fluxo rápido (após design inline ser aprovado)
+
+## Entrada
+- Blueprint em `.aioson/squads/.designs/<slug>.blueprint.json`
+- Se não existe blueprint: instrua o usuário a rodar `@squad design <slug>` primeiro
+- OU: se o usuário chamou `@squad` sem subcomando, rode design + create em sequência
+
+## Processo
+
+### Passo 1 — Ler blueprint
+Leia `.aioson/squads/.designs/<slug>.blueprint.json` e valide que os campos obrigatórios existem (slug, name, problem, goal, mode, executors).
+
+### Passo 2 — Criar estrutura de diretórios
+```
+.aioson/squads/<slug>/
+├── agents/
+│   ├── agents.md              # Manifesto textual
+│   ├── orquestrador.md        # Orquestrador
+│   └── <executor-slug>.md     # Um por executor
+├── skills/
+├── templates/
+├── docs/
+│   ├── design-doc.md
+│   └── readiness.md
+└── squad.manifest.json        # Manifesto JSON formal
+
+output/<slug>/                  # Diretório de output
+aios-logs/<slug>/               # Diretório de logs
+media/<slug>/                   # Diretório de mídia
+```
+
+### Passo 3 — Gerar squad.manifest.json
+Monte o manifesto a partir do blueprint. O JSON deve seguir o schema `squad-manifest.schema.json`. Copie executors, skills, mcps, genomes, contentBlueprints do blueprint. Adicione package paths e rules.
+
+### Passo 4 — Gerar agents.md (manifesto textual)
+Siga o formato existente no squad.md atual:
+```markdown
+# Squad <name>
+
+## Mission
+[do blueprint.mission]
+
+## Does
+[derivado do scope]
+
+## Does not do
+[derivado do outOfScope]
+
+## Permanent executors
+- @orquestrador — [role]
+- @<slug> — [role]
+
+## Squad skills
+## Squad MCPs
+## Subagent policy
+## Outputs and review
+```
+
+### Passo 5 — Gerar cada executor
+Para cada executor no blueprint, crie `.aioson/squads/<slug>/agents/<executor-slug>.md` seguindo o template atual do squad.md (seção "Step 2 — Generate each specialist agent"):
+- Header com `# Agent @<slug>` + bloco ACTIVATED
+- Mission, Quick context, Active genomes, Focus, Response standard, Hard constraints, Output contract
+
+### Passo 6 — Gerar orquestrador
+Crie `.aioson/squads/<slug>/agents/orquestrador.md` seguindo o template atual (seção "Step 3 — Generate the orchestrator").
+
+### Passo 7 — Gerar docs
+- `docs/design-doc.md`: resumo do design derivado do blueprint
+- `docs/readiness.md`: estado de readiness derivado do blueprint
+
+### Passo 8 — Registrar nos gateways
+Atualize `CLAUDE.md` e `AGENTS.md` no root do projeto conforme as regras existentes no squad.md.
+
+### Passo 9 — Salvar metadata
+Salve `.aioson/squads/<slug>/squad.md` no formato existente.
+
+### Passo 10 — Rodar validate
+Após criar tudo, execute mentalmente a task squad-validate (leia `.aioson/tasks/squad-validate.md`) para verificar que o pacote está consistente.
+
+### Passo 11 — Warm-up round
+Siga as regras existentes no squad.md: mostre cada especialista com problem reading, initial recommendation, main risk, suggested next step.
+
+## Saída
+- Pacote completo em `.aioson/squads/<slug>/`
+- CLAUDE.md e AGENTS.md atualizados
+- Warm-up round executado
+
+## Regras
+- SEMPRE leia o blueprint antes de gerar
+- SIGA os templates de executor e orquestrador do squad.md original
+- MANTENHA o HTML deliverable após cada rodada (regra existente)
+- NÃO pule o warm-up — é mandatório

package/template/.aioson/tasks/squad-design.md

@@ -0,0 +1,100 @@
+# Task: Squad Design
+
+> Fase de design do lifecycle do squad. Produz um blueprint intermediário.
+
+## Quando usar
+- `@squad design <nome>` — invocação direta
+- `@squad` sem subcomando quando não existe blueprint para o slug
+
+## Entrada
+- Contexto do usuário: domínio, objetivo, constraints, roles desejados
+- Opcional: documentação fonte (arquivos `.md`, texto colado, screenshots)
+- Opcional: domínio hint para guiar a análise
+
+## Processo
+
+### Passo 0 — Verificar artisan input e templates disponíveis
+
+Se o usuário forneceu `--from-artisan <id>`:
+1. Procure `.aioson/squads/.artisan/<id>.md`
+2. Se encontrar, leia o Squad PRD
+3. Extraia: domain, goal, mode, executors propostos, skills, constraints, content blueprints
+4. Use como base para o blueprint — pule para o Passo 5 (calcular readiness)
+5. Mostre ao usuário: "Li o PRD do Artisan. Posso gerar o blueprint com base nele — quer ajustar algo?"
+
+Caso contrário, verifique templates:
+Verifique se existe `.aioson/templates/squads/`. Se existir, liste os templates disponíveis e pergunte:
+"Quer partir de um template? Opções: content-basic, research-analysis, software-delivery, media-channel — ou começar do zero."
+Se o usuário escolher um template, leia o `template.json` e use como base para o blueprint (executores, content blueprints, mode).
+
+### Passo 1 — Coletar contexto mínimo
+Pergunte em um bloco só (não faça múltiplas rodadas):
+1. Domínio ou tópico do squad
+2. Problema principal ou objetivo
+3. Tipo de output esperado (artigos, scripts, código, análise, etc.)
+4. Constraints (audiência, tom, nível técnico, idioma)
+5. (opcional) Roles específicos desejados
+
+Se o usuário já forneceu contexto suficiente (texto, docs, imagens), infira as respostas e siga em frente. Pergunte somente se há lacunas materiais.
+
+### Passo 2 — Derivar design-doc mental
+Antes de definir executores, consolide:
+- Problema que está sendo resolvido
+- Objetivo prático do squad
+- Scope e out-of-scope
+- Risks e assumptions
+- Skills e docs que precisam entrar no contexto
+- Mode do squad (content | software | research | mixed)
+
+### Passo 3 — Definir executores
+Determine 3-5 roles especializados. Para cada executor, defina:
+- slug (kebab-case)
+- title
+- role (uma frase)
+- focus (3-5 bullets)
+- skills que vai usar
+- genomes que herda
+
+Inclua sempre um `orquestrador`.
+
+### Passo 4 — Definir content blueprints
+Se o squad é content-oriented, defina pelo menos 1 content blueprint com:
+- slug, contentType, layoutType
+- sections com key, label, blockTypes
+
+### Passo 5 — Calcular readiness
+Avalie cada dimensão:
+- contextReady: há contexto suficiente?
+- blueprintReady: o blueprint está completo?
+- generationReady: dá para gerar os executores?
+
+### Passo 6 — Gerar blueprint JSON
+Salve o blueprint em `.aioson/squads/.designs/<slug>.blueprint.json`
+
+O JSON deve seguir o schema `squad-blueprint.schema.json`.
+
+Gere um UUID para o campo `id`. Use `new Date().toISOString()` para `createdAt`.
+
+### Passo 7 — Apresentar resumo
+Mostre ao usuário:
+- Executores propostos com roles
+- Content blueprints definidos
+- Assumptions feitas
+- Risks identificados
+- Readiness status
+- Confidence score
+
+Pergunte se quer ajustar algo antes de criar.
+
+## Saída
+- Arquivo: `.aioson/squads/.designs/<slug>.blueprint.json`
+- Resumo no chat para review do usuário
+
+## Próximo passo
+- Se aprovado: `@squad create <slug>` (que lê o blueprint e gera o pacote)
+- Se precisa ajuste: o usuário indica e o design é atualizado
+
+## Regras
+- NÃO crie o pacote do squad aqui — isso é responsabilidade da task create
+- NÃO pule o blueprint — ele é obrigatório
+- MANTENHA o blueprint leve — o LLM preenche lacunas na fase create

package/template/.aioson/tasks/squad-export.md

@@ -0,0 +1,20 @@
+# Task: Squad Export
+
+> Empacota um squad para reutilização em outro projeto.
+
+## Quando usar
+- `@squad export <slug>`
+
+## Processo
+
+1. Validar o squad (rodar validate)
+2. Se inválido: abortar com sugestão de correção
+3. Coletar todos os arquivos do pacote:
+   - .aioson/squads/<slug>/ (tudo)
+   - NÃO incluir: output/, aios-logs/, media/ (são dados de sessão)
+4. Gerar archive: `.aioson/squads/exports/<slug>.aios-squad.tar.gz`
+5. Incluir um `import-instructions.md` no archive
+
+## Saída
+- Arquivo .tar.gz portável
+- Instruções de import no chat