up-cc 0.1.0

package/references/questioning.md

@@ -0,0 +1,156 @@
+<questioning_guide>
+
+Project initialization is dream extraction, not requirements gathering. You're helping the user discover and articulate what they want to build. This isn't a contract negotiation - it's collaborative thinking.
+
+<philosophy>
+
+**You are a thinking partner, not an interviewer.**
+
+The user often has a fuzzy idea. Your job is to help them sharpen it. Ask questions that make them think "oh, I hadn't considered that" or "yes, that's exactly what I mean."
+
+Don't interrogate. Collaborate. Don't follow a script. Follow the thread.
+
+</philosophy>
+
+<the_goal>
+
+By the end of questioning, you need enough clarity to write a PROJECT.md that downstream phases can act on:
+
+- **Research** needs: what domain to research, what the user already knows, what unknowns exist
+- **Requirements** needs: clear enough vision to scope v1 features
+- **Roadmap** needs: clear enough vision to decompose into phases, what "done" looks like
+- **plan-phase** needs: specific requirements to break into tasks, context for implementation choices
+- **execute-phase** needs: success criteria to verify against, the "why" behind requirements
+
+A vague PROJECT.md forces every downstream phase to guess. The cost compounds.
+
+</the_goal>
+
+<how_to_question>
+
+**Start open.** Let them dump their mental model. Don't interrupt with structure.
+
+**Follow energy.** Whatever they emphasized, dig into that. What excited them? What problem sparked this?
+
+**Challenge vagueness.** Never accept fuzzy answers. "Good" means what? "Users" means who? "Simple" means how?
+
+**Make the abstract concrete.** "Walk me through using this." "What does that actually look like?"
+
+**Surface assumptions.** "You're assuming X - is that right?" "What if that's not true?"
+
+**Find edges.** "What's NOT part of this?" "Where does this end?"
+
+**Reveal motivation.** "What prompted this?" "What are you doing today that this replaces?"
+
+**Know when to stop.** When you understand what they want, why they want it, who it's for, and what done looks like - offer to proceed.
+
+</how_to_question>
+
+<question_types>
+
+Use these as inspiration, not a checklist. Pick what's relevant to the thread.
+
+**Motivation - why this exists:**
+- "What prompted this?"
+- "What are you doing today that this replaces?"
+- "What would you do if this existed?"
+
+**Concreteness - what it actually is:**
+- "Walk me through using this"
+- "You said X - what does that actually look like?"
+- "Give me an example"
+
+**Clarification - what they mean:**
+- "When you say Z, do you mean A or B?"
+- "You mentioned X - tell me more about that"
+
+**Success - how you'll know it's working:**
+- "How will you know this is working?"
+- "What does done look like?"
+
+</question_types>
+
+<using_askuserquestion>
+
+Use AskUserQuestion to help users think by presenting concrete options to react to.
+
+**Good options:**
+- Interpretations of what they might mean
+- Specific examples to confirm or deny
+- Concrete choices that reveal priorities
+
+**Bad options:**
+- Generic categories ("Technical", "Business", "Other")
+- Leading options that presume an answer
+- Too many options (2-4 is ideal)
+- Headers longer than 12 characters (hard limit)
+
+**Example - vague answer:**
+User says "it should be fast"
+
+- header: "Fast"
+- question: "Fast how?"
+- options: ["Sub-second response", "Handles large datasets", "Quick to build", "Let me explain"]
+
+**Example - following a thread:**
+User mentions "frustrated with current tools"
+
+- header: "Frustration"
+- question: "What specifically frustrates you?"
+- options: ["Too many clicks", "Missing features", "Unreliable", "Let me explain"]
+
+</using_askuserquestion>
+
+<freeform_rule>
+
+**When the user wants to explain freely, STOP using AskUserQuestion.**
+
+If a user selects "Other" and their response signals they want to describe something in their own words, you MUST:
+
+1. **Ask your follow-up as plain text** - NOT via AskUserQuestion
+2. **Wait for them to type at the normal prompt**
+3. **Resume AskUserQuestion** only after processing their freeform response
+
+</freeform_rule>
+
+<context_checklist>
+
+Use this as a **background checklist**, not a conversation structure. Check these mentally as you go. If gaps remain, weave questions naturally.
+
+- [ ] What they're building (concrete enough to explain to a stranger)
+- [ ] Why it needs to exist (the problem or desire driving it)
+- [ ] Who it's for (even if just themselves)
+- [ ] What "done" looks like (observable outcomes)
+
+Four things. If they volunteer more, capture it.
+
+</context_checklist>
+
+<decision_gate>
+
+When you could write a clear PROJECT.md, offer to proceed:
+
+- header: "Ready?"
+- question: "I think I understand what you're after. Ready to create PROJECT.md?"
+- options:
+  - "Create PROJECT.md" - Let's move forward
+  - "Keep exploring" - I want to share more / ask me more
+
+If "Keep exploring" - ask what they want to add or identify gaps and probe naturally.
+
+</decision_gate>
+
+<anti_patterns>
+
+- **Checklist walking** - Going through domains regardless of what they said
+- **Canned questions** - "What's your core value?" regardless of context
+- **Corporate speak** - "What are your success criteria?" "Who are your stakeholders?"
+- **Interrogation** - Firing questions without building on answers
+- **Rushing** - Minimizing questions to get to "the work"
+- **Shallow acceptance** - Taking vague answers without probing
+- **Premature constraints** - Asking about tech stack before understanding the idea
+- **User skills** - NEVER ask about user's technical experience. Claude builds.
+
+</anti_patterns>
+
+</questioning_guide>

package/references/ui-brand.md

@@ -0,0 +1,124 @@
+<ui_patterns>
+
+Visual patterns for user-facing UP output. Orchestrators @-reference this file.
+
+## Stage Banners
+
+Use for major workflow transitions.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ UP > {ACAO}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Action names (uppercase, Portuguese):**
+- `QUESTIONANDO`
+- `PESQUISANDO`
+- `PLANEJANDO FASE {N}`
+- `EXECUTANDO`
+- `VERIFICANDO`
+- `PROGRESSO`
+- `PAUSANDO`
+- `RETOMANDO`
+- `TAREFA RAPIDA`
+- `FASE {N} COMPLETA`
+
+---
+
+## Completion Banner
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ UP > FASE {N} COMPLETA
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+---
+
+## Checkpoint Boxes
+
+User action required. 62-character width.
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  CHECKPOINT: {Type}                                          ║
+╚══════════════════════════════════════════════════════════════╝
+
+{Content}
+
+──────────────────────────────────────────────────────────────
+-> {ACTION PROMPT}
+──────────────────────────────────────────────────────────────
+```
+
+**Types:**
+- `CHECKPOINT: Verification Required` -> `-> Type "approved" or describe issues`
+- `CHECKPOINT: Decision Required` -> `-> Select: option-a / option-b`
+- `CHECKPOINT: Action Required` -> `-> Type "done" when complete`
+
+---
+
+## Status Symbols
+
+```
+✓  Complete / Passed / Verified
+✗  Failed / Missing / Blocked
+◆  In Progress
+○  Pending
+⚡ Auto-approved
+⚠  Warning
+```
+
+---
+
+## Progress Display
+
+**Phase level:**
+```
+Progress: ████████░░ 80%
+```
+
+**Task level:**
+```
+Tasks: 2/4 complete
+```
+
+---
+
+## Error Box
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+{Error description}
+
+**To fix:** {Resolution steps}
+```
+
+---
+
+## Tables
+
+```
+| Phase | Status | Tasks | Progress |
+|-------|--------|-------|----------|
+| 1     | ✓      | 3/3   | 100%     |
+| 2     | ◆      | 1/4   | 25%      |
+| 3     | ○      | 0/2   | 0%       |
+```
+
+---
+
+## Anti-Patterns
+
+- Varying box/banner widths
+- Mixing banner styles (`===`, `---`, `***`)
+- Skipping `UP >` prefix in banners
+- Using `GSD` instead of `UP` in banners
+- Random emoji usage
+- Using `►` instead of `>` in banners
+
+</ui_patterns>

package/templates/config.json

@@ -0,0 +1,6 @@
+{
+  "modo": "solo",
+  "paralelizacao": true,
+  "commit_docs": true,
+  "auto_advance": false
+}

package/templates/continue-here.md

@@ -0,0 +1,78 @@
+# Continue-Here Template
+
+Copy and fill this structure for `.plano/fases/XX-name/.continue-aqui.md`:
+
+```yaml
+---
+phase: XX-name
+task: 3
+total_tasks: 7
+status: in_progress
+last_updated: 2025-01-15T14:30:00Z
+---
+```
+
+```markdown
+<estado_atual>
+[Where exactly are we? What's the immediate context?]
+</estado_atual>
+
+<trabalho_concluido>
+[What got done this session - be specific]
+
+- Task 1: [name] - Done
+- Task 2: [name] - Done
+- Task 3: [name] - In progress, [what's done on it]
+</trabalho_concluido>
+
+<trabalho_restante>
+[What's left in this phase]
+
+- Task 3: [name] - [what's left to do]
+- Task 4: [name] - Not started
+- Task 5: [name] - Not started
+</trabalho_restante>
+
+<decisoes_tomadas>
+[Key decisions and why - so next session doesn't re-debate]
+
+- Decided to use [X] because [reason]
+- Chose [approach] over [alternative] because [reason]
+</decisoes_tomadas>
+
+<bloqueios>
+[Anything stuck or waiting on external factors]
+
+- [Blocker 1]: [status/workaround]
+</bloqueios>
+
+<contexto>
+[Mental state, "vibe", anything that helps resume smoothly]
+
+[What were you thinking about? What was the plan?
+This is the "pick up exactly where you left off" context.]
+</contexto>
+
+<proxima_acao>
+[The very first thing to do when resuming]
+
+Start with: [specific action]
+</proxima_acao>
+```
+
+<yaml_fields>
+Required YAML frontmatter:
+
+- `phase`: Directory name (e.g., `02-authentication`)
+- `task`: Current task number
+- `total_tasks`: How many tasks in phase
+- `status`: `in_progress`, `blocked`, `almost_done`
+- `last_updated`: ISO timestamp
+</yaml_fields>
+
+<guidelines>
+- Be specific enough that a fresh Claude instance understands immediately
+- Include WHY decisions were made, not just what
+- The `<proxima_acao>` should be actionable without reading anything else
+- This file gets DELETED after resume - it's not permanent storage
+</guidelines>

package/templates/project.md

@@ -0,0 +1,184 @@
+# PROJECT.md Template
+
+Template for `.plano/PROJECT.md` -- the living project context document.
+
+<template>
+
+```markdown
+# [Project Name]
+
+## What This Is
+
+[Current accurate description -- 2-3 sentences. What does this product do and who is it for?
+Use the user's language and framing. Update whenever reality drifts from this description.]
+
+## Core Value
+
+[The ONE thing that matters most. If everything else fails, this must work.
+One sentence that drives prioritization when tradeoffs arise.]
+
+## Requirements
+
+### Validated
+
+<!-- Shipped and confirmed valuable. -->
+
+(None yet -- ship to validate)
+
+### Active
+
+<!-- Current scope. Building toward these. -->
+
+- [ ] [Requirement 1]
+- [ ] [Requirement 2]
+- [ ] [Requirement 3]
+
+### Out of Scope
+
+<!-- Explicit boundaries. Includes reasoning to prevent re-adding. -->
+
+- [Exclusion 1] -- [why]
+- [Exclusion 2] -- [why]
+
+## Context
+
+[Background information that informs implementation:
+- Technical environment or ecosystem
+- Relevant prior work or experience
+- User research or feedback themes
+- Known issues to address]
+
+## Constraints
+
+- **[Type]**: [What] -- [Why]
+- **[Type]**: [What] -- [Why]
+
+Common types: Tech stack, Timeline, Budget, Dependencies, Compatibility, Performance, Security
+
+## Key Decisions
+
+<!-- Decisions that constrain future work. Add throughout project lifecycle. -->
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| [Choice] | [Why] | [Good / Revisit / Pending] |
+
+---
+*Last updated: [date] after [trigger]*
+```
+
+</template>
+
+<guidelines>
+
+**What This Is:**
+- Current accurate description of the product
+- 2-3 sentences capturing what it does and who it's for
+- Use the user's words and framing
+- Update when the product evolves beyond this description
+
+**Core Value:**
+- The single most important thing
+- Everything else can fail; this cannot
+- Drives prioritization when tradeoffs arise
+- Rarely changes; if it does, it's a significant pivot
+
+**Requirements -- Validated:**
+- Requirements that shipped and proved valuable
+- Format: `- [x] [Requirement] -- [version/phase]`
+- These are locked -- changing them requires explicit discussion
+
+**Requirements -- Active:**
+- Current scope being built toward
+- These are hypotheses until shipped and validated
+- Move to Validated when shipped, Out of Scope if invalidated
+
+**Requirements -- Out of Scope:**
+- Explicit boundaries on what we're not building
+- Always include reasoning (prevents re-adding later)
+- Includes: considered and rejected, deferred to future, explicitly excluded
+
+**Context:**
+- Background that informs implementation decisions
+- Technical environment, prior work, user feedback
+- Known issues or technical debt to address
+- Update as new context emerges
+
+**Constraints:**
+- Hard limits on implementation choices
+- Tech stack, timeline, budget, compatibility, dependencies
+- Include the "why" -- constraints without rationale get questioned
+
+**Key Decisions:**
+- Significant choices that affect future work
+- Add decisions as they're made throughout the project
+- Track outcome when known:
+  - Good -- decision proved correct
+  - Revisit -- decision may need reconsideration
+  - Pending -- too early to evaluate
+
+**Last Updated:**
+- Always note when and why the document was updated
+- Format: `after Phase 2` or `after v1.0`
+- Triggers review of whether content is still accurate
+
+</guidelines>
+
+<evolution>
+
+PROJECT.md evolves throughout the project lifecycle.
+
+**After each phase transition:**
+1. Requirements invalidated? Move to Out of Scope with reason
+2. Requirements validated? Move to Validated with phase reference
+3. New requirements emerged? Add to Active
+4. Decisions to log? Add to Key Decisions
+5. "What This Is" still accurate? Update if drifted
+
+**After significant milestones:**
+1. Full review of all sections
+2. Core Value check -- still the right priority?
+3. Audit Out of Scope -- reasons still valid?
+4. Update Context with current state
+
+</evolution>
+
+<brownfield>
+
+For existing codebases:
+
+1. **Map codebase first** via `/up:mapear`
+
+2. **Infer Validated requirements** from existing code:
+   - What does the codebase actually do?
+   - What patterns are established?
+   - What's clearly working and relied upon?
+
+3. **Gather Active requirements** from user:
+   - Present inferred current state
+   - Ask what they want to build next
+
+4. **Initialize:**
+   - Validated = inferred from existing code
+   - Active = user's goals for this work
+   - Out of Scope = boundaries user specifies
+   - Context = includes current codebase state
+
+</brownfield>
+
+<state_reference>
+
+STATE.md references PROJECT.md:
+
+```markdown
+## Referencia do Projeto
+
+Ver: .plano/PROJECT.md (atualizado [data])
+
+**Valor central:** [One-liner from Core Value section]
+**Foco atual:** [Current phase name]
+```
+
+This ensures Claude reads current PROJECT.md context.
+
+</state_reference>

package/templates/requirements.md

@@ -0,0 +1,129 @@
+# Requirements Template
+
+Template for `.plano/REQUIREMENTS.md` -- checkable requirements that define "done."
+
+<template>
+
+```markdown
+# Requirements: [Project Name]
+
+**Defined:** [date]
+**Core Value:** [from PROJECT.md]
+
+## v1 Requirements
+
+Requirements for initial release. Each maps to roadmap phases.
+
+### Authentication
+
+- [ ] **AUTH-01**: User can sign up with email and password
+- [ ] **AUTH-02**: User receives email verification after signup
+- [ ] **AUTH-03**: User can reset password via email link
+- [ ] **AUTH-04**: User session persists across browser refresh
+
+### [Category 2]
+
+- [ ] **[CAT]-01**: [Requirement description]
+- [ ] **[CAT]-02**: [Requirement description]
+- [ ] **[CAT]-03**: [Requirement description]
+
+### [Category 3]
+
+- [ ] **[CAT]-01**: [Requirement description]
+- [ ] **[CAT]-02**: [Requirement description]
+
+## v2 Requirements
+
+Deferred to future release. Tracked but not in current roadmap.
+
+### [Category]
+
+- **[CAT]-01**: [Requirement description]
+- **[CAT]-02**: [Requirement description]
+
+## Out of Scope
+
+Explicitly excluded. Documented to prevent scope creep.
+
+| Feature | Reason |
+|---------|--------|
+| [Feature] | [Why excluded] |
+| [Feature] | [Why excluded] |
+
+## Traceability
+
+Which phases cover which requirements. Updated during roadmap creation.
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| AUTH-01 | Phase 1 | Pending |
+| AUTH-02 | Phase 1 | Pending |
+| AUTH-03 | Phase 1 | Pending |
+| AUTH-04 | Phase 1 | Pending |
+| [REQ-ID] | Phase [N] | Pending |
+
+**Coverage:**
+- v1 requirements: [X] total
+- Mapped to phases: [Y]
+- Unmapped: [Z]
+
+---
+*Requirements defined: [date]*
+*Last updated: [date] after [trigger]*
+```
+
+</template>
+
+<guidelines>
+
+**Requirement Format:**
+- ID: `[CATEGORY]-[NUMBER]` (AUTH-01, CONTENT-02, SOCIAL-03)
+- Description: User-centric, testable, atomic
+- Checkbox: Only for v1 requirements (v2 are not yet actionable)
+
+**Categories:**
+- Derive from project domain
+- Keep consistent with domain conventions
+- Typical: Authentication, Content, Social, Notifications, Moderation, Payments, Admin
+
+**v1 vs v2:**
+- v1: Committed scope, will be in roadmap phases
+- v2: Acknowledged but deferred, not in current roadmap
+- Moving v2 to v1 requires roadmap update
+
+**Out of Scope:**
+- Explicit exclusions with reasoning
+- Prevents "why didn't you include X?" later
+
+**Traceability:**
+- Empty initially, populated during roadmap creation
+- Each requirement maps to exactly one phase
+- Unmapped requirements = roadmap gap
+
+**Status Values:**
+- Pending: Not started
+- In Progress: Phase is active
+- Complete: Requirement verified
+- Blocked: Waiting on external factor
+
+</guidelines>
+
+<evolution>
+
+**After each phase completes:**
+1. Mark covered requirements as Complete
+2. Update traceability status
+3. Note any requirements that changed scope
+
+**After roadmap updates:**
+1. Verify all v1 requirements still mapped
+2. Add new requirements if scope expanded
+3. Move requirements to v2/out of scope if descoped
+
+**Requirement completion criteria:**
+- Requirement is "Complete" when:
+  - Feature is implemented
+  - Feature is verified (tests pass, manual check done)
+  - Feature is committed
+
+</evolution>