How this skill is triggered — by the user, by Claude, or both
Slash command
/chama:architectThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
You act with 3 roles simultaneously:
You act with 3 roles simultaneously:
Your job is to execute one idea per iteration and complete this flow:
Read project.language from .chama.yml. Respond in the configured language. Default: pt-BR.
REPO="${CHAMA_REPO:-$(yq '.project.repo' .chama.yml 2>/dev/null)}"
OWNER="${CHAMA_OWNER:-$(yq '.github.owner' .chama.yml 2>/dev/null)}"
PROJECT_NUM="${CHAMA_PROJECT_NUMBER:-$(yq '.github.project_number' .chama.yml 2>/dev/null)}"
# Board statuses (configurable via .chama.yml, with defaults)
STATUS_TODO=$(yq '.github.board_statuses.todo // "Todo"' .chama.yml 2>/dev/null || echo 'Todo')
.chama.yml (project config)CLAUDE.md (root and per-component — auto-loaded)Read knowledge_paths from .chama.yml. If the field is absent or empty, skip this section entirely (backward compatible).
KNOWLEDGE_PATHS=$(yq '.knowledge_paths[]' .chama.yml 2>/dev/null)
For each path in KNOWLEDGE_PATHS:
.md, .yml, .yaml, .txt:FILES=$(find "$KPATH" -type f \( -name "*.md" -o -name "*.yml" -o -name "*.yaml" -o -name "*.txt" \) 2>/dev/null)
FILE_COUNT=$(echo "$FILES" | grep -c . 2>/dev/null || echo 0)
TOTAL_KB=$(echo "$FILES" | xargs du -k 2>/dev/null | awk '{s+=$1} END {print s+0}')
"⚠️ WARNING: Knowledge path '<path>' has <N> files (<X>KB). Consider using more specific paths to reduce context size.""🚫 CRITICAL: Knowledge path '<path>' ignored (<N> files, <X>KB). Exceeds limits (max 15 files or 200KB). Reorganize into more specific paths."Present a summary of knowledge paths processing before proceeding:
Knowledge paths summary:
- docs/architecture/ → 5 files (32KB) ✅
- docs/domain/ → 12 files (150KB) ⚠️ WARNING
- docs/all/ → 25 files (500KB) 🚫 SKIPPED
IDEA_ISSUE — GitHub Issue number with label ideaIf IDEA_ISSUE is not provided:
idea:gh issue list --repo "$REPO" --label "idea" --state open
gh issue view "$IDEA_ISSUE" --repo "$REPO"
Before the Spec, consolidate the architectural vision:
IMPORTANT: Do NOT read existing Spec issues to learn the format. Use ONLY the resolved template below as the structure.
ROOT_DIR="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
SPEC_TEMPLATE=$("$ROOT_DIR/scripts/resolve-spec-template.sh")
Read the resolved SPEC_TEMPLATE content. Use it as the sole structure for the Spec Issue. Fill in each section with the architectural analysis from steps 1 and 2.
Write the filled Spec to a temp file and create the issue using --body-file to avoid shell escaping issues:
# Write filled spec to temp file
cat > /tmp/chama-spec-body.md <<'SPECEOF'
<filled spec content here>
SPECEOF
SPEC_URL=$(gh issue create \
--repo "$REPO" \
--label "spec" \
--title "spec: <Spec title>" \
--body-file /tmp/chama-spec-body.md)
rm -f /tmp/chama-spec-body.md
For each phase, write the body to a temp file and create the issue using --body-file:
cat > /tmp/chama-phase-body.md <<'PHASEEOF'
## Spec
- #SPEC_NUMBER
## Objective
- <objective>
## Scope
- <item 1>
- <item 2>
## Acceptance Criteria
- [ ] <criterion 1>
- [ ] <criterion 2>
## Tests
- [ ] <test scenario>
PHASEEOF
PHASE_URL=$(gh issue create \
--repo "$REPO" \
--label "phase" \
--title "phase: [Spec #SPEC_NUMBER] Phase N - <name>" \
--body-file /tmp/chama-phase-body.md)
rm -f /tmp/chama-phase-body.md
For each phase issue created, add it to the project and set status to Todo:
PROJECT_ID=$(gh project list --owner "$OWNER" --format json | jq -r ".projects[] | select(.number == $PROJECT_NUM) | .id")
FIELD_ID=$(gh project field-list "$PROJECT_NUM" --owner "$OWNER" --format json | jq -r '.fields[] | select(.name == "Status") | .id')
OPTION_ID_TODO=$(gh project field-list "$PROJECT_NUM" --owner "$OWNER" --format json | jq -r --arg status "$STATUS_TODO" '.fields[] | select(.name == "Status") | .options[] | select(.name == $status) | .id')
# Add phase to project
gh project item-add "$PROJECT_NUM" --owner "$OWNER" --url "$PHASE_URL"
# Extract phase issue number from URL (last segment)
PHASE_NUMBER=$(echo "$PHASE_URL" | grep -oP '\d+$')
# Wait for GitHub to index the new item, then set status to Todo
sleep 3
ITEM_ID=$(gh project item-list "$PROJECT_NUM" --owner "$OWNER" --format json | jq -r --argjson num "$PHASE_NUMBER" '.items[] | select(.content.number == $num) | .id')
# Retry once if ITEM_ID is empty (API indexing delay)
if [ -z "$ITEM_ID" ] || [ "$ITEM_ID" = "null" ]; then
sleep 3
ITEM_ID=$(gh project item-list "$PROJECT_NUM" --owner "$OWNER" --format json | jq -r --argjson num "$PHASE_NUMBER" '.items[] | select(.content.number == $num) | .id')
fi
if [ -n "$ITEM_ID" ] && [ "$ITEM_ID" != "null" ]; then
gh project item-edit --project-id "$PROJECT_ID" --id "$ITEM_ID" --field-id "$FIELD_ID" --single-select-option-id "$OPTION_ID_TODO"
else
echo "WARNING: Could not set status for phase #$PHASE_NUMBER — item not found in project. Status may need manual update."
fi
gh issue close "$IDEA_ISSUE" --repo "$REPO" --comment "Converted to Spec #SPEC_NUMBER. Phases created."
Finish only when:
specphaseTodoRespond with:
Todo)npx claudepluginhub rafaelportugal/chama --plugin chamaPlans new projects or major epics by exploring domain, defining boundaries and architecture, decomposing into phased features, and producing a project plan artifact. Use for multi-feature work.
Refines rough ideas into executable specifications via collaborative questioning, alternative exploration, and incremental validation. Invoke before creative work or implementation.