knowns 0.3.0 → 0.4.0

package/CLAUDE.md

@@ -1,3 +1,5 @@
+/Users/howznguyen/Workspaces/Knowns/knowns/src/templates/knowns-guidelines-cli.md
+
 <!-- KNOWNS GUIDELINES START -->
 # Knowns CLI Guidelines
 
@@ -232,8 +234,8 @@ $ knowns task create "Add password reset flow" \
 
 # Output: Created task AUTH-042
 
-# 2. Take the task and start timer
-$ knowns task edit AUTH-042 -s in-progress -a @me
+# 2. Take the task and start timer (uses defaultAssignee or @me fallback)
+$ knowns task edit AUTH-042 -s in-progress -a $(knowns config get defaultAssignee --plain || echo "@me")
 $ knowns time start AUTH-042
 
 # Output: Timer started for AUTH-042
@@ -306,17 +308,24 @@ $ knowns task edit AUTH-042 -s done
 ### Step 1: Take Task
 
 ```bash
-knowns task edit <id> -s in-progress -a @me
+# Assign using defaultAssignee from config (falls back to @me if not set)
+knowns task edit <id> -s in-progress -a $(knowns config get defaultAssignee --plain || echo "@me")
 ```
 
-> **Note**: `@me` is a special keyword that assigns the task to yourself. You can also use specific usernames like `@harry` or `@john`.
+> **Note**: The `defaultAssignee` is configured in `.knowns/config.json` during `knowns init`. If not set, `@me` is used as fallback. To update: `knowns config set defaultAssignee "@username"`
 
-### Step 2: Start Time Tracking
+### Step 2: Start Time Tracking (REQUIRED)
 
 ```bash
 knowns time start <id>
 ```
 
+> **CRITICAL**: Time tracking is MANDATORY. Always start timer when taking a task and stop when done. This data is essential for:
+> - Accurate project estimation
+> - Identifying bottlenecks
+> - Resource planning
+> - Sprint retrospectives
+
 ### Step 3: Read Related Documentation
 
 > **FOR AI AGENTS**: This step is MANDATORY, not optional. You must understand the codebase before planning.
@@ -352,11 +361,43 @@ knowns task edit <id> --plan $'1. Research patterns (see @doc/security-patterns)
 ### Step 5: Implement
 
 ```bash
-# Check acceptance criteria as you complete them
-knowns task edit <id> --check-ac 1 --check-ac 2 --check-ac 3
+# Work through implementation plan step by step
+# IMPORTANT: Only check AC AFTER completing the work, not before
+
+# After completing work for AC #1:
+knowns task edit <id> --check-ac 1
+knowns task edit <id> --append-notes "✓ Completed: <brief description>"
+
+# After completing work for AC #2:
+knowns task edit <id> --check-ac 2
+knowns task edit <id> --append-notes "✓ Completed: <brief description>"
+```
+
+> **CRITICAL**: Never check an AC before the work is actually done. ACs represent completed outcomes, not intentions.
+
+### Step 6: Handle Dynamic Requests (During Implementation)
+
+If the user adds new requirements during implementation:
+
+```bash
+# Add new acceptance criteria
+knowns task edit <id> --ac "New requirement from user"
+
+# Update implementation plan to include new steps
+knowns task edit <id> --plan $'1. Original step 1
+2. Original step 2
+3. NEW: Handle user request for X
+4. Continue with remaining work'
+
+# Append note about scope change
+knowns task edit <id> --append-notes "⚠️ Scope updated: Added requirement for X per user request"
+
+# Continue with Step 5 (Implement) for new requirements
 ```
 
-### Step 6: Add Implementation Notes
+> **Note**: Always document scope changes. This helps track why a task took longer than expected.
+
+### Step 7: Add Implementation Notes
 
 ```bash
 # Add comprehensive notes (suitable for PR description)
@@ -373,18 +414,77 @@ knowns task edit <id> --append-notes "✓ Implemented middleware"
 knowns task edit <id> --append-notes "✓ Added tests"
 ```
 
-### Step 7: Stop Time Tracking
+### Step 8: Stop Time Tracking (REQUIRED)
 
 ```bash
 knowns time stop
 ```
 
-### Step 8: Complete Task
+> **CRITICAL**: Never forget to stop the timer. If you forget, use manual entry: `knowns time add <id> <duration> -n "Forgot to stop timer"`
+
+### Step 9: Complete Task
 
 ```bash
 knowns task edit <id> -s done
 ```
 
+### Step 10: Handle Post-Completion Changes (If Applicable)
+
+If the user requests changes or updates AFTER task is marked done:
+
+```bash
+# 1. Reopen task - set back to in-progress
+knowns task edit <id> -s in-progress
+
+# 2. Restart time tracking (REQUIRED)
+knowns time start <id>
+
+# 3. Add new AC for the changes requested
+knowns task edit <id> --ac "Post-completion fix: <description>"
+
+# 4. Document the reopen reason
+knowns task edit <id> --append-notes "🔄 Reopened: User requested changes - <reason>"
+
+# 5. Follow Step 5-9 again (Implement → Notes → Stop Timer → Done)
+```
+
+> **CRITICAL**: Treat post-completion changes as a mini-workflow. Always:
+> - Reopen task (in-progress)
+> - Start timer again
+> - Add AC for traceability
+> - Document why it was reopened
+> - Follow the same completion process
+
+### Step 11: Knowledge Extraction (Post-Completion)
+
+After completing a task, extract reusable knowledge to docs:
+
+```bash
+# Search if similar pattern already documented
+knowns search "<pattern/concept>" --type doc --plain
+
+# If new knowledge, create a doc for future reference
+knowns doc create "Pattern: <Name>" \
+    -d "Reusable pattern discovered during task implementation" \
+    -t "pattern,<domain>" \
+    -f "patterns"
+
+# Or append to existing doc
+knowns doc edit "<existing-doc>" -a "## New Section\n\nLearned from task <id>: ..."
+
+# Reference the source task
+knowns doc edit "<doc-name>" -a "\n\n> Source: @task-<id>"
+```
+
+**When to extract knowledge:**
+- New patterns/conventions discovered
+- Common error solutions
+- Reusable code snippets or approaches
+- Integration patterns with external services
+- Performance optimization techniques
+
+> **CRITICAL**: Only extract **generalizable** knowledge. Task-specific details belong in implementation notes, not docs.
+
 ---
 
 ## Essential Commands
@@ -400,7 +500,7 @@ knowns task edit <id> -t "New title"
 knowns task edit <id> -d "New description"
 knowns task edit <id> -s in-progress
 knowns task edit <id> --priority high
-knowns task edit <id> -a @me
+knowns task edit <id> -a <assignee>              # $(knowns config get defaultAssignee --plain || echo "@me")
 
 # Acceptance Criteria
 knowns task edit <id> --ac "New criterion"           # Add
@@ -418,7 +518,7 @@ knowns task <id> --plain                             # Shorthand (ALWAYS use --p
 knowns task view <id> --plain                        # Full command
 knowns task list --plain
 knowns task list --status in-progress --plain
-knowns task list --assignee @me --plain
+knowns task list --assignee <assignee> --plain   # $(knowns config get defaultAssignee --plain || echo "@me")
 knowns task list --tree --plain                      # Tree hierarchy
 ```
 
@@ -582,10 +682,11 @@ A task is **Done** ONLY when **ALL** criteria are met:
 
 ### Via CLI (Required)
 
-- [ ] All acceptance criteria checked: `--check-ac <index>`
+- [ ] All acceptance criteria checked: `--check-ac <index>` (only after work is actually done)
 - [ ] Implementation notes added: `--notes "..."`
-- [ ] Timer stopped: `knowns time stop`
+- [ ] ⏱️ Timer stopped: `knowns time stop` (MANDATORY - do not skip!)
 - [ ] Status set to done: `-s done`
+- [ ] Knowledge extracted to docs (if applicable)
 
 ### Via Code (Required)
 
@@ -626,6 +727,8 @@ Use **lowercase with hyphens**:
 |-------|-------|
 | Edit .md files directly | Use `knowns task edit` |
 | Change `- [ ]` to `- [x]` in file | Use `--check-ac <index>` |
+| Check AC before completing work | Only check AC AFTER work is actually done |
+| Skip time tracking | ALWAYS use `time start` and `time stop` |
 | Start coding without reading docs | Read ALL related docs FIRST |
 | Skip `knowns doc list` on new project | Always list docs when starting |
 | Assume you know the conventions | Read CONVENTIONS/ARCHITECTURE docs |
@@ -638,7 +741,7 @@ Use **lowercase with hyphens**:
 | Mark done without all criteria | Check ALL criteria first |
 | Write implementation steps in AC | Write outcome-oriented criteria |
 | Use `"In Progress"` or `"Done"` | Use `in-progress`, `done` |
-| Use `@yourself` | Use `@me` or specific username |
+| Use `@yourself` or unknown assignee | Use `$(knowns config get defaultAssignee --plain \|\| echo "@me")` |
 | Ignore refs in task description | Follow ALL refs (`@.knowns/...`) before planning |
 | See `@.knowns/docs/...` but don't read | Use `knowns doc "<path>" --plain` |
 | See `@.knowns/tasks/task-X` but don't check | Use `knowns task X --plain` for context |
@@ -682,6 +785,26 @@ EOF
 - **Unix/macOS**: Use forward slashes: `./docs/api.md`
 - **Windows**: Both work, but prefer forward slashes for consistency
 
+### Windows Command Line Limit
+
+Windows has ~8191 character limit. For long content, append in chunks:
+
+```bash
+# 1. Create or reset with short content
+knowns doc edit "doc-name" -c "## Overview\n\nShort intro."
+
+# 2. Append each section separately
+knowns doc edit "doc-name" -a "## Section 1\n\nContent..."
+knowns doc edit "doc-name" -a "## Section 2\n\nMore content..."
+```
+
+Or use file-based options:
+
+```bash
+knowns doc edit "doc-name" --content-file ./content.md
+knowns doc edit "doc-name" --append-file ./more.md
+```
+
 ---
 
 ## Best Practices Checklist
@@ -701,7 +824,7 @@ EOF
 - [ ] Related docs searched: `knowns search "keyword" --type doc --plain`
 - [ ] ALL relevant docs read: `knowns doc "Doc Name" --plain`
 - [ ] Similar done tasks reviewed for patterns
-- [ ] Task assigned to self: `-a @me`
+- [ ] Task assigned to self: `-a $(knowns config get defaultAssignee --plain || echo "@me")`
 - [ ] Status set to in-progress: `-s in-progress`
 - [ ] Timer started: `knowns time start <id>`
 
@@ -714,12 +837,13 @@ EOF
 
 ### After Work
 
-- [ ] All acceptance criteria checked
+- [ ] All acceptance criteria checked (only after work is done)
 - [ ] Implementation notes added: `--notes "..."`
 - [ ] Timer stopped: `knowns time stop`
 - [ ] Tests passing
 - [ ] Documentation updated
 - [ ] Status set to done: `-s done`
+- [ ] Knowledge extracted to docs (if applicable): patterns, solutions, conventions
 
 ---
 
@@ -734,22 +858,26 @@ knowns doc "CONVENTIONS" --plain
 
 # === FULL WORKFLOW ===
 knowns task create "Title" -d "Description" --ac "Criterion"
-knowns task edit <id> -s in-progress -a @me
-knowns time start <id>
+knowns task edit <id> -s in-progress -a $(knowns config get defaultAssignee --plain || echo "@me")
+knowns time start <id>                                     # ⏱️ REQUIRED: Start timer
 knowns search "keyword" --type doc --plain
 knowns doc "Doc Name" --plain
 knowns search "keyword" --type task --status done --plain  # Learn from history
 knowns task edit <id> --plan $'1. Step (see @doc/file)\n2. Step'
 # ... wait for approval, then implement ...
-knowns task edit <id> --check-ac 1 --check-ac 2
-knowns task edit <id> --append-notes "✓ Completed feature"
-knowns time stop
+# Only check AC AFTER completing the work:
+knowns task edit <id> --check-ac 1
+knowns task edit <id> --append-notes "✓ Completed: feature X"
+knowns task edit <id> --check-ac 2
+knowns task edit <id> --append-notes "✓ Completed: feature Y"
+knowns time stop                                           # ⏱️ REQUIRED: Stop timer
 knowns task edit <id> -s done
+# Optional: Extract knowledge to docs if generalizable patterns found
 
 # === VIEW & SEARCH ===
 knowns task <id> --plain                                   # Shorthand for view
 knowns task list --plain
-knowns task list --status in-progress --assignee @me --plain
+knowns task list --status in-progress --assignee $(knowns config get defaultAssignee --plain || echo "@me") --plain
 knowns search "query" --plain
 knowns search "bug" --type task --status in-progress --plain
 
@@ -782,7 +910,3 @@ knowns doc edit "doc-name" -a "Appended content"
 
 
 
-
-
-
-

package/README.md

@@ -98,7 +98,7 @@ knowns browser  # Open Web UI
 | **Documentation** | Nested folders with markdown support |
 | **Time Tracking** | Built-in timers and reports |
 | **Context Linking** | `@task-42` and `@doc/patterns/auth` references |
-| **AI Integration** | MCP Server for Claude, `--plain` output |
+| **AI Integration** | MCP Server, `--plain` output, guideline templates |
 | **Web UI** | Kanban board, doc browser, dark mode |
 
 ---
@@ -119,6 +119,11 @@ knowns doc "doc-name" --plain               # View doc (shorthand)
 # Time & Search
 knowns time start <id> && knowns time stop
 knowns search "query" --plain
+
+# AI Guidelines
+knowns agents sync                          # Sync CLAUDE.md, AGENTS.md
+knowns agents sync --gemini                 # Compact version for Gemini
+knowns agents sync --type mcp               # MCP tools format
 ```
 
 ---
@@ -134,6 +139,8 @@ knowns search "query" --plain
 | [MCP Integration](./docs/mcp-integration.md) | Claude Desktop setup |
 | [Configuration](./docs/configuration.md) | Project structure and options |
 | [AI Workflow](./docs/ai-workflow.md) | Guide for AI agents |
+| [Developer Guide](./docs/developer-guide.md) | Technical docs for contributors |
+| [Changelog](./CHANGELOG.md) | Version history |
 
 ---