aios-core 2.3.1 → 3.1.0

package/.aios-core/development/tasks/github-devops-github-pr-automation.md

@@ -262,22 +262,209 @@ function extractStoryInfo(storyPath) {
 }
 ```
 
-### Step 4: Generate PR Title
+### Step 4: Generate PR Title (Configurable Format)
+
+> **Configuration-Driven:** PR title format is controlled by `core-config.yaml` → `github.pr.title_format`
+> This allows each project to choose the format that matches their workflow.
 
 ```javascript
+const yaml = require('js-yaml');
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Load PR configuration from core-config.yaml
+ * @returns {Object} PR configuration with defaults
+ */
+function loadPRConfig() {
+  const configPath = path.join(process.cwd(), '.aios-core', 'core-config.yaml');
+
+  // Default configuration (for projects without core-config)
+  const defaults = {
+    title_format: 'story-first',  // Safe default for most projects
+    include_story_id: true,
+    conventional_commits: {
+      enabled: false,
+      branch_type_map: {
+        'feature/': 'feat',
+        'feat/': 'feat',
+        'fix/': 'fix',
+        'bugfix/': 'fix',
+        'hotfix/': 'fix',
+        'docs/': 'docs',
+        'chore/': 'chore',
+        'refactor/': 'refactor',
+        'test/': 'test',
+        'perf/': 'perf',
+        'ci/': 'ci',
+        'style/': 'style',
+        'build/': 'build'
+      },
+      default_type: 'feat'
+    }
+  };
+
+  try {
+    if (fs.existsSync(configPath)) {
+      const config = yaml.load(fs.readFileSync(configPath, 'utf8'));
+      return { ...defaults, ...config?.github?.pr };
+    }
+  } catch (error) {
+    console.warn('Could not load core-config.yaml, using defaults');
+  }
+
+  return defaults;
+}
+
+/**
+ * Generate PR title based on project configuration.
+ *
+ * Supported formats (configured in core-config.yaml → github.pr.title_format):
+ *
+ * 1. "conventional" - Conventional Commits format (for semantic-release)
+ *    Example: "feat(auth): implement OAuth login [Story 6.17]"
+ *
+ * 2. "story-first" - Story ID first (legacy/simple projects)
+ *    Example: "[Story 6.17] Implement OAuth Login"
+ *
+ * 3. "branch-based" - Branch name converted to title
+ *    Example: "Feature User Auth"
+ *
+ * @param {string} branchName - Current git branch name
+ * @param {Object} storyInfo - Story information (id, title)
+ * @returns {string} Formatted PR title
+ */
 function generatePRTitle(branchName, storyInfo) {
+  const config = loadPRConfig();
+  const format = config.title_format || 'story-first';
+
+  switch (format) {
+    case 'conventional':
+      return generateConventionalTitle(branchName, storyInfo, config);
+    case 'story-first':
+      return generateStoryFirstTitle(branchName, storyInfo, config);
+    case 'branch-based':
+      return generateBranchBasedTitle(branchName, storyInfo, config);
+    default:
+      return generateStoryFirstTitle(branchName, storyInfo, config);
+  }
+}
+
+/**
+ * Format: {type}({scope}): {description} [Story {id}]
+ * Used for: Projects with semantic-release automation
+ */
+function generateConventionalTitle(branchName, storyInfo, config) {
+  const typeMap = config.conventional_commits?.branch_type_map || {};
+  const defaultType = config.conventional_commits?.default_type || 'feat';
+
+  // Detect commit type from branch prefix
+  let type = defaultType;
+  for (const [prefix, commitType] of Object.entries(typeMap)) {
+    if (branchName.startsWith(prefix)) {
+      type = commitType;
+      break;
+    }
+  }
+
+  // Extract scope from branch name (e.g., feat/auth/login -> scope=auth)
+  const scopeMatch = branchName.match(/^[a-z-]+\/([a-z-]+)\//);
+  const scope = scopeMatch ? scopeMatch[1] : null;
+  const scopeStr = scope ? `(${scope})` : '';
+
+  // Generate description
+  if (storyInfo && storyInfo.id && storyInfo.title) {
+    let cleanTitle = storyInfo.title
+      .replace(/^Story\s*\d+\.\d+[:\s-]*/i, '')
+      .trim();
+    cleanTitle = cleanTitle.charAt(0).toLowerCase() + cleanTitle.slice(1);
+
+    const storyRef = config.include_story_id ? ` [Story ${storyInfo.id}]` : '';
+    return `${type}${scopeStr}: ${cleanTitle}${storyRef}`;
+  }
+
+  // Fallback: convert branch name to description
+  const description = branchName
+    .replace(/^(feature|feat|fix|bugfix|hotfix|docs|chore|refactor|test|perf|ci|style|build)\//, '')
+    .replace(/^[a-z-]+\//, '')
+    .replace(/-/g, ' ')
+    .toLowerCase()
+    .trim();
+
+  return `${type}${scopeStr}: ${description}`;
+}
+
+/**
+ * Format: [Story {id}] {Title}
+ * Used for: Simple projects, legacy workflows, non-NPM projects
+ */
+function generateStoryFirstTitle(branchName, storyInfo, config) {
   if (storyInfo && storyInfo.id && storyInfo.title) {
     return `[Story ${storyInfo.id}] ${storyInfo.title}`;
   }
 
   // Fallback: convert branch name to title
   return branchName
-    .replace(/^feature\//, '')
+    .replace(/^(feature|feat|fix|bugfix|hotfix|docs|chore|refactor|test|perf|ci|style|build)\//, '')
     .replace(/-/g, ' ')
     .replace(/\b\w/g, c => c.toUpperCase());
 }
+
+/**
+ * Format: {Branch Name As Title}
+ * Used for: Minimal projects, quick iterations
+ */
+function generateBranchBasedTitle(branchName, storyInfo, config) {
+  const title = branchName
+    .replace(/^(feature|feat|fix|bugfix|hotfix|docs|chore|refactor|test|perf|ci|style|build)\//, '')
+    .replace(/-/g, ' ')
+    .replace(/\b\w/g, c => c.toUpperCase());
+
+  if (config.include_story_id && storyInfo?.id) {
+    return `${title} [Story ${storyInfo.id}]`;
+  }
+
+  return title;
+}
+```
+
+## Configuration Reference
+
+Add to your project's `core-config.yaml`:
+
+```yaml
+github:
+  pr:
+    # Options: conventional | story-first | branch-based
+    title_format: conventional  # For semantic-release projects
+    # title_format: story-first  # For simple projects (default)
+
+    include_story_id: true
+
+    conventional_commits:
+      enabled: true
+      branch_type_map:
+        feature/: feat
+        fix/: fix
+        docs/: docs
+        # Add custom mappings as needed
+      default_type: feat
+
+  semantic_release:
+    enabled: true  # Set false if not using semantic-release
 ```
 
+## Title Format Examples
+
+| Format | Branch | Story | Generated Title |
+|--------|--------|-------|-----------------|
+| `conventional` | `feature/user-auth` | 6.17: User Auth | `feat: user auth [Story 6.17]` |
+| `conventional` | `fix/cli/parsing` | 6.18: CLI Fix | `fix(cli): cLI fix [Story 6.18]` |
+| `story-first` | `feature/user-auth` | 6.17: User Auth | `[Story 6.17] User Auth` |
+| `story-first` | `fix/cli-bug` | - | `Cli Bug` |
+| `branch-based` | `feature/user-auth` | 6.17 | `User Auth [Story 6.17]` |
+| `branch-based` | `docs/readme` | - | `Readme` |
+
 ### Step 5: Generate PR Description
 
 ```javascript
@@ -415,10 +602,60 @@ Called by `@github-devops` via `*create-pr` command.
 ## Validation
 
 - PR created in correct repository (detected URL)
-- PR title includes story ID if available
+- PR title follows Conventional Commits format (required for semantic-release)
+- PR title includes story ID if available (e.g., `[Story 6.17]`)
 - PR description includes repository context
 - Base branch is correct (usually main/master)
 
+## Semantic-Release Integration (Optional)
+
+> **Note:** This section only applies when `core-config.yaml` has:
+> - `github.pr.title_format: conventional`
+> - `github.semantic_release.enabled: true`
+>
+> Projects without semantic-release should use `title_format: story-first` (default).
+
+**When enabled:** PRs merged via "Squash and merge" use the PR title as commit message, triggering semantic-release:
+
+| Branch Pattern | Generated Title | Release |
+|---------------|-----------------|---------|
+| `feature/user-auth` | `feat: user auth` | ✅ Minor |
+| `feat/auth/sso-login` | `feat(auth): sso login` | ✅ Minor |
+| `fix/cli-parsing` | `fix: cli parsing` | ✅ Patch |
+| `docs/readme-update` | `docs: readme update` | ❌ None |
+| `chore/deps-update` | `chore: deps update` | ❌ None |
+
+For breaking changes, manually edit the PR title to include `!`:
+- `feat!: redesign authentication API [Story 7.1]`
+
+## Configuration for Different Project Types
+
+### NPM Package with Semantic-Release (aios-core)
+```yaml
+github:
+  pr:
+    title_format: conventional
+  semantic_release:
+    enabled: true
+```
+
+### Simple Web App (no releases)
+```yaml
+github:
+  pr:
+    title_format: story-first  # [Story 6.17] Title
+  semantic_release:
+    enabled: false
+```
+
+### Quick Prototypes
+```yaml
+github:
+  pr:
+    title_format: branch-based  # Just branch name as title
+    include_story_id: false
+```
+
 ## Notes
 
 - Works with ANY repository

package/.aios-core/development/tasks/squad-creator-create.md

@@ -0,0 +1,289 @@
+---
+task: Create Squad
+responsavel: "@squad-creator"
+responsavel_type: agent
+atomic_layer: task
+Entrada: |
+  - name: Nome do squad (kebab-case, obrigatorio)
+  - description: Descricao (opcional, elicitacao)
+  - author: Autor (opcional, default: git config user.name)
+  - license: Licenca (opcional, default: MIT)
+  - template: Template base (basic | etl | agent-only)
+  - config_mode: extend | override | none
+Saida: |
+  - squad_path: Caminho do squad criado
+  - manifest: Conteudo do squad.yaml gerado
+  - next_steps: Instrucoes para proximos passos
+Checklist:
+  - "[ ] Validar nome (kebab-case, nao existe)"
+  - "[ ] Coletar informacoes via elicitacao"
+  - "[ ] Gerar estrutura de diretorios"
+  - "[ ] Gerar squad.yaml"
+  - "[ ] Gerar arquivos de config (coding-standards, etc.)"
+  - "[ ] Gerar exemplo de agent"
+  - "[ ] Gerar exemplo de task"
+  - "[ ] Executar validacao inicial"
+  - "[ ] Exibir proximos passos"
+---
+
+# *create-squad
+
+Cria um novo squad seguindo a arquitetura task-first do AIOS.
+
+## Uso
+
+```
+@squad-creator
+
+*create-squad
+# → Modo interativo, elicita todas as informacoes
+
+*create-squad meu-squad
+# → Usa defaults para o resto
+
+*create-squad meu-squad --template etl --author "Meu Nome"
+# → Especifica opcoes diretamente
+```
+
+## Parametros
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `name` | string | - | Squad name (kebab-case, required) |
+| `--description` | string | "Custom squad" | Squad description |
+| `--author` | string | git user.name | Author name |
+| `--license` | string | MIT | License type |
+| `--template` | string | basic | Template: basic, etl, agent-only |
+| `--config-mode` | string | extend | Config inheritance: extend, override, none |
+| `--skip-validation` | flag | false | Skip initial validation |
+| `--yes` | flag | false | Skip interactive prompts, use defaults |
+
+## Elicitacao Interativa
+
+```
+? Squad name: meu-dominio-squad
+? Description: Squad para automacao de processos X
+? Author: [git config user.name]
+? License: (MIT)
+  > MIT
+    Apache-2.0
+    ISC
+    UNLICENSED
+? Template:
+  > basic (estrutura minima)
+    etl (processamento de dados)
+    agent-only (apenas agentes)
+? Include example agent? (Y/n)
+? Include example task? (Y/n)
+? Config inheritance:
+  > extend (adiciona as regras do core)
+    override (substitui regras do core)
+    none (sem heranca)
+? Minimum AIOS version: (2.1.0)
+```
+
+## Templates Disponiveis
+
+| Template | Description | Components |
+|----------|-------------|------------|
+| `basic` | Estrutura minima | 1 agent, 1 task |
+| `etl` | Processamento de dados | 2 agents, 3 tasks, scripts |
+| `agent-only` | Apenas agentes | 2 agents, sem tasks |
+
+## Estrutura Gerada
+
+```
+./squads/meu-dominio-squad/
+├── squad.yaml                    # Manifest
+├── README.md                     # Documentacao
+├── config/
+│   ├── coding-standards.md      # Extends/override core
+│   ├── tech-stack.md            # Tecnologias do squad
+│   └── source-tree.md           # Estrutura documentada
+├── agents/
+│   └── example-agent.md         # Agente de exemplo
+├── tasks/
+│   └── example-agent-task.md    # Task de exemplo
+├── checklists/
+│   └── .gitkeep
+├── workflows/
+│   └── .gitkeep
+├── templates/
+│   └── .gitkeep
+├── tools/
+│   └── .gitkeep
+├── scripts/
+│   └── .gitkeep
+└── data/
+    └── .gitkeep
+```
+
+## squad.yaml Gerado
+
+```yaml
+name: meu-dominio-squad
+version: 1.0.0
+description: Squad para automacao de processos X
+author: Meu Nome
+license: MIT
+slashPrefix: meu-dominio
+
+aios:
+  minVersion: "2.1.0"
+  type: squad
+
+components:
+  tasks:
+    - example-agent-task.md
+  agents:
+    - example-agent.md
+  workflows: []
+  checklists: []
+  templates: []
+  tools: []
+  scripts: []
+
+config:
+  extends: extend
+  coding-standards: config/coding-standards.md
+  tech-stack: config/tech-stack.md
+  source-tree: config/source-tree.md
+
+dependencies:
+  node: []
+  python: []
+  squads: []
+
+tags:
+  - custom
+  - automation
+```
+
+## Flow
+
+```
+1. Parse arguments
+   ├── If name provided → validate kebab-case
+   └── If no name → prompt for name
+
+2. Check if squad exists
+   ├── If exists → error with suggestion
+   └── If not exists → continue
+
+3. Collect configuration
+   ├── If --yes flag → use all defaults
+   └── If interactive → elicit each option
+
+4. Generate squad structure
+   ├── Create directories
+   ├── Generate squad.yaml from template
+   ├── Generate config files
+   ├── Generate example agent (if requested)
+   ├── Generate example task (if requested)
+   └── Add .gitkeep to empty directories
+
+5. Run initial validation
+   ├── If --skip-validation → skip
+   └── If validation → run squad-validator
+
+6. Display success message
+   └── Show next steps
+```
+
+## Output de Sucesso
+
+```
+✅ Squad created successfully!
+
+📁 Location: ./squads/meu-dominio-squad/
+
+📋 Next steps:
+   1. cd squads/meu-dominio-squad
+   2. Customize squad.yaml with your details
+   3. Create your agents in agents/
+   4. Create tasks in tasks/ (task-first!)
+   5. Validate: @squad-creator *validate-squad meu-dominio-squad
+
+📚 Documentation:
+   - Squad Guide: docs/guides/squads-guide.md
+   - Task Format: .aios-core/docs/standards/TASK-FORMAT-SPECIFICATION-V1.md
+
+🚀 When ready to share:
+   - Local only: Keep in ./squads/ (private)
+   - Public: @squad-creator *publish-squad meu-dominio-squad
+   - API: @squad-creator *sync-squad-synkra meu-dominio-squad
+```
+
+## Error Handling
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| `INVALID_NAME` | Name not kebab-case | Use lowercase with hyphens |
+| `SQUAD_EXISTS` | Squad already exists | Choose different name or delete existing |
+| `PERMISSION_DENIED` | Can't write to squads/ | Check directory permissions |
+| `VALIDATION_FAILED` | Generated squad invalid | Check error details, fix manually |
+
+## Implementation
+
+```javascript
+const { SquadGenerator } = require('./.aios-core/development/scripts/squad');
+const { SquadValidator } = require('./.aios-core/development/scripts/squad');
+
+async function createSquad(options) {
+  const {
+    name,
+    description,
+    author,
+    license,
+    template,
+    configMode,
+    skipValidation,
+    includeAgent,
+    includeTask,
+    aiosMinVersion
+  } = options;
+
+  // Validate name
+  if (!/^[a-z][a-z0-9-]*[a-z0-9]$/.test(name)) {
+    throw new Error('INVALID_NAME: Squad name must be kebab-case');
+  }
+
+  // Generate squad
+  const generator = new SquadGenerator();
+  const result = await generator.generate({
+    name,
+    description,
+    author,
+    license,
+    template,
+    configMode,
+    includeAgent,
+    includeTask,
+    aiosMinVersion
+  });
+
+  // Validate (unless skipped)
+  if (!skipValidation) {
+    const validator = new SquadValidator();
+    const validation = await validator.validate(result.path);
+    if (!validation.valid) {
+      console.warn('Warning: Generated squad has validation issues');
+      console.warn(validator.formatResult(validation, result.path));
+    }
+  }
+
+  // Display success
+  console.log(`\n✅ Squad created successfully!\n`);
+  console.log(`📁 Location: ${result.path}/\n`);
+  displayNextSteps(name);
+
+  return result;
+}
+```
+
+## Related
+
+- **Agent:** @squad-creator (Craft)
+- **Script:** squad-generator.js
+- **Validator:** squad-validator.js (SQS-3)
+- **Loader:** squad-loader.js (SQS-2)