Documentation
¶
Overview ¶
Package add provides the "ctx add" command for appending entries to context files.
It supports adding decisions, tasks, learnings, and conventions to their respective files in the .context/ directory. Content can be provided via command argument, --file flag, or stdin pipe.
Supported entry types (defined in config.FileType):
- decision/decisions: Appends to DECISIONS.md
- task/tasks: Inserts into TASKS.md before first unchecked task, or under a named section when --section is provided
- learning/learnings: Appends to LEARNINGS.md
- convention/conventions: Appends to CONVENTIONS.md
Example usage:
ctx add decision "Use PostgreSQL for primary database" ctx add task "Implement auth" --priority high --section "Phase 1" ctx add learning --file notes.md echo "Use camelCase" | ctx add convention
Index ¶
- func AppendEntry(existing []byte, entry string, fileType string, section string) []byte
- func Cmd() *cobra.Command
- func FormatConvention(content string) string
- func FormatDecision(title, context, rationale, consequences string) string
- func FormatLearning(title, context, lesson, application string) string
- func FormatTask(content string, priority string) string
- func GenerateIndex(entries []DecisionEntry) string
- func GenerateIndexTable(entries []IndexEntry, columnHeader string) string
- func UpdateIndex(content string) string
- func UpdateLearningsIndex(content string) string
- func ValidateEntry(params EntryParams) error
- func WriteEntry(params EntryParams) error
- type DecisionEntry
- type EntryParams
- type IndexEntry
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AppendEntry ¶
AppendEntry inserts a formatted entry into existing file content.
For tasks, inserts after the target section header. For decisions and learnings, inserts before existing entries (reverse-chronological order). For conventions, appends to the end of the file.
Parameters:
- existing: Current file content as bytes
- entry: Pre-formatted entry text to insert
- fileType: Entry type (e.g., "task", "decision", "learning", "convention")
- section: Target section header for tasks; defaults to "## Next Up" if empty; a "## " prefix is added automatically if missing
Returns:
- []byte: Modified file content with the entry inserted
func Cmd ¶
Cmd returns the "ctx add" command for appending entries to context files.
Supported types are defined in config.FileType (both singular and plural forms accepted, e.g., "decision" or "decisions"). Content can be provided via command argument, --file flag, or stdin pipe.
Flags:
- --priority, -p: Priority level for tasks (high, medium, low)
- --section, -s: Target section within the file
- --file, -f: Read content from a file instead of argument
- --context, -c: Context for decisions/learnings (required)
- --rationale, -r: Rationale for decisions (required for decisions)
- --consequences: Consequences for decisions (required for decisions)
- --lesson, -l: Lesson for learnings (required for learnings)
- --application, -a: Application for learnings (required for learnings)
Returns:
- *cobra.Command: Configured add command with flags registered
func FormatConvention ¶
FormatConvention formats a convention entry as a simple Markdown list item.
Format: "- content"
Parameters:
- content: Convention description text
Returns:
- string: Formatted convention line with trailing newline
func FormatDecision ¶
FormatDecision formats a decision entry as a structured Markdown section.
The output includes a timestamped heading, status, and complete ADR sections for context, rationale, and consequences.
Parameters:
- title: Decision title/summary text
- context: What prompted this decision
- rationale: Why this choice over alternatives
- consequences: What changes as a result
Returns:
- string: Formatted decision section with all ADR fields
func FormatLearning ¶
FormatLearning formats a learning entry as a structured Markdown section.
The output includes a timestamped heading and complete sections for context, lesson, and application.
Parameters:
- title: Learning title/summary text
- context: What prompted this learning
- lesson: The key insight
- application: How to apply this going forward
Returns:
- string: Formatted learning section with all fields
func FormatTask ¶
FormatTask formats a task entry as a Markdown checkbox item.
The output includes a timestamp tag for session correlation and an optional priority tag. Format: "- [ ] content #priority:level #added:YYYY-MM-DD-HHMMSS"
Parameters:
- content: Task description text
- priority: Priority level (high, medium, low); empty string omits the tag
Returns:
- string: Formatted task line with trailing newline
func GenerateIndex ¶ added in v0.2.0
func GenerateIndex(entries []DecisionEntry) string
GenerateIndex creates a Markdown table for decisions.
This is a convenience wrapper for backward compatibility.
Parameters:
- entries: Slice of decision entries to include
Returns:
- string: Markdown table or empty string if no entries
func GenerateIndexTable ¶ added in v0.2.0
func GenerateIndexTable(entries []IndexEntry, columnHeader string) string
GenerateIndexTable creates a Markdown table index from entries.
Delegates to index.GenerateTable.
Parameters:
- entries: Slice of entries to include
- columnHeader: Header for the second column (e.g., "Decision", "Learning")
Returns:
- string: Markdown table (without markers) or empty string
func UpdateIndex ¶ added in v0.2.0
UpdateIndex regenerates the decision index in DECISIONS.md content.
Delegates to index.UpdateDecisions.
Parameters:
- content: The full content of DECISIONS.md
Returns:
- string: Updated content with regenerated index
func UpdateLearningsIndex ¶ added in v0.2.0
UpdateLearningsIndex regenerates the learning index in LEARNINGS.md content.
Delegates to index.UpdateLearnings.
Parameters:
- content: The full content of LEARNINGS.md
Returns:
- string: Updated content with regenerated index
func ValidateEntry ¶ added in v0.2.0
func ValidateEntry(params EntryParams) error
ValidateEntry checks that required fields are present for the given entry type.
Parameters:
- params: Entry parameters to validate
Returns:
- error: Non-nil with details about missing fields, nil if valid
func WriteEntry ¶ added in v0.2.0
func WriteEntry(params EntryParams) error
WriteEntry formats and writes an entry to the appropriate context file.
This function handles the complete write cycle: read existing content, format the entry, append it, write back, and update the index if needed.
Parameters:
- params: EntryParams containing type, content, and optional fields
Returns:
- error: Non-nil if type is unknown, the file doesn't exist, or write fails
Types ¶
type DecisionEntry ¶ added in v0.2.0
DecisionEntry is an alias for IndexEntry for backward compatibility.
func ParseDecisionHeaders ¶ added in v0.2.0
func ParseDecisionHeaders(content string) []DecisionEntry
ParseDecisionHeaders extracts all entries from file content.
This is an alias for ParseEntryHeaders for backward compatibility.
Parameters:
- content: The full content of a context file
Returns:
- []DecisionEntry: Slice of parsed entries (it may be empty)
type EntryParams ¶ added in v0.2.0
type EntryParams struct {
Type string
Content string
Section string
Priority string
Context string
Rationale string
Consequences string
Lesson string
Application string
}
EntryParams contains all parameters needed to add an entry to a context file.
Fields:
- Type: Entry type (decision, learning, task, convention)
- Content: Title or main content
- Section: Target section (for tasks)
- Priority: Priority level (for tasks)
- Context: Context field (for decisions/learnings)
- Rationale: Rationale (for decisions)
- Consequences: Consequences (for decisions)
- Lesson: Lesson (for learnings)
- Application: Application (for learnings)
type IndexEntry ¶ added in v0.2.0
IndexEntry represents a parsed entry header from a context file.
This is an alias for index.Entry for backward compatibility.
func ParseEntryHeaders ¶ added in v0.2.0
func ParseEntryHeaders(content string) []IndexEntry
ParseEntryHeaders extracts all entries from file content.
Delegates to index.ParseHeaders.
Parameters:
- content: The full content of a context file
Returns:
- []IndexEntry: Slice of parsed entries (may be empty)
Source Files