artifact

package
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 6, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Approval 

type Approval struct {
	Status        string // "approved", "approved_with_nits"
	Timestamp     time.Time
	RemainingWork []string // Nits deferred to future
	ReadyForPR    bool
	Summary       string
}

Approval represents final review approval

type ArchitectureDecision 

type ArchitectureDecision struct {
	Title        string   // Decision title
	Alternatives []string // Alternatives considered
	Rationale    string   // Why this choice was made
	TradeOffs    []string // Trade-offs of this decision
	LayerImpact  []string // Which layers are impacted
}

ArchitectureDecision represents an ADR embedded in the planning artifact

type Artifact 

type Artifact struct {
	Type      ArtifactType
	Feature   string    // Feature name (e.g., "user-auth")
	FilePath  string    // Full path to artifact file
	CreatedAt time.Time // When artifact was created
	UpdatedAt time.Time // When artifact was last updated
	Status    string    // "in_progress", "completed", "archived"
}

Artifact represents a base artifact with common fields

type ArtifactType 

type ArtifactType string

ArtifactType represents the type of artifact being generated 

const (
	ArtifactTypePlanning  ArtifactType = "planning"
	ArtifactTypeExecution ArtifactType = "execution"
	ArtifactTypeReview    ArtifactType = "review"
)

type Chain 

type Chain struct {
	Feature           string
	PlanningArtifact  string // Path to planning.md
	ExecutionArtifact string // Path to execution.md
	ReviewArtifact    string // Path to review.md
	PRDocument        string // Path to pr-{number}.md (if archived)
	IsArchived        bool
	ArchivePath       string // Path to archive directory if archived
}

Chain represents a linked chain of artifacts (planning → execution → review → PR)

type ChainManager 

type ChainManager struct {
	// contains filtered or unexported fields
}

ChainManager handles artifact chain operations

func NewChainManager 

func NewChainManager(docsRoot string) *ChainManager

NewChainManager creates a new chain manager

func (*ChainManager) FindChain 

func (m *ChainManager) FindChain(feature string) (*Chain, error)

FindChain discovers the artifact chain for a given feature Looks in both active directories and archives 

func (m *ChainManager) UpdateLinks(chain *Chain) error

UpdateLinks updates the artifact chain links in all artifact files This is called after moving artifacts to archive or when creating new artifacts

type CodeContract 

type CodeContract struct {
	Layer       string // "domain", "application", "infrastructure", "interface"
	FilePath    string // Where this contract lives
	Code        string // Go code for interface/type
	Description string // What this contract does
}

CodeContract represents interface definitions and type signatures

type CommandLog 

type CommandLog struct {
	Timestamp time.Time
	Tool      string
	Args      map[string]any
	Result    string
	Impact    string // "readonly", "modifying", "destructive"
}

CommandLog represents a preserved command from execution

type CompactionClient 

type CompactionClient interface {
	// Complete sends a prompt to the model and returns the response
	Complete(ctx context.Context, model string, prompt string) (string, error)
}

CompactionClient is an interface for calling LLM models.

type CompactionConfig 

type CompactionConfig struct {
	ContextThreshold  float64  // Trigger at 80% of context window
	TaskInterval      int      // Also trigger every N tasks
	TokenThreshold    int      // Also trigger when artifact exceeds N tokens
	TargetReduction   float64  // Aim to reduce by 70%
	PreserveCommands  bool     // Never summarize tool calls
	PreserveDecisions bool     // Never lose architectural choices
	Models            []string // Compaction models to try (in order)
}

CompactionConfig holds configuration for artifact compaction

func DefaultCompactionConfig 

func DefaultCompactionConfig() CompactionConfig

DefaultCompactionConfig returns sensible defaults

type CompactionResult 

type CompactionResult struct {
	OriginalTokens    int
	CompactedTokens   int
	ReductionPercent  float64
	TasksCompacted    int
	CommandsPreserved int
	Model             string
	Duration          time.Duration
}

CompactionResult represents the result of artifact compaction

type Compactor 

type Compactor struct {
	// contains filtered or unexported fields
}

Compactor handles artifact compaction

func NewCompactor 

func NewCompactor(config CompactionConfig, modelClient CompactionClient, tokenCounter TokenCounter) *Compactor

NewCompactor creates a new artifact compactor

func (*Compactor) Compact 

func (c *Compactor) Compact(ctx context.Context, artifact *ExecutionArtifact, tasksToCompact []TaskProgress) (*CompactionResult, string, error)

Compact performs compaction on an execution artifact Returns compacted tasks section and compaction result

func (*Compactor) ShouldCompact 

func (c *Compactor) ShouldCompact(artifact *ExecutionArtifact, contextWindowSize int) (bool, string)

ShouldCompact determines if an execution artifact should be compacted

type ContextSection 

type ContextSection struct {
	ExistingPatterns  []string  // Patterns detected in codebase
	ArchitectureStyle string    // "DDD", "Pragmatic CRUD", "Layered", etc.
	RelevantFiles     []string  // Files analyzed for context
	UserGoal          string    // User's stated goal
	ResearchSummary   string    // Condensed research brief summary
	ResearchRisks     []string  // Top risks discovered during research
	ResearchLogPath   string    // Path to research log file
	ResearchLoggedAt  time.Time // Timestamp of research brief generation
}

ContextSection captures the codebase context analyzed during planning

type CrossCuttingConcerns 

type CrossCuttingConcerns struct {
	ErrorHandling string   // Error handling strategy
	Logging       string   // Logging approach
	Testing       string   // Testing requirements
	Security      []string // Security considerations
}

CrossCuttingConcerns captures system-wide concerns

type Deviation 

type Deviation struct {
	TaskID      int
	Type        string // "Added", "Changed", "Removed"
	Description string
	Rationale   string
	Impact      string // "Low", "Medium", "High"
}

Deviation tracks deviations from the plan

type ExecutionArtifact 

type ExecutionArtifact struct {
	Artifact
	PlanningArtifactPath string
	StartedAt            time.Time
	CurrentTask          int // Which task is in progress
	TotalTasks           int
	ProgressLog          []TaskProgress
	Pauses               []ExecutionPause
	DeviationSummary     []Deviation
	ReviewChecklist      []string // High-risk areas for review
}

ExecutionArtifact tracks implementation progress

type ExecutionPause 

type ExecutionPause struct {
	Number       int
	TaskID       int
	Reason       string // "Business Logic Ambiguity", "Architectural Conflict", etc.
	Question     string
	UserResponse string
	Resolution   string
	Timestamp    time.Time
}

ExecutionPause represents when execution paused for user input

type ExecutionTracker 

type ExecutionTracker struct {
	// contains filtered or unexported fields
}

ExecutionTracker manages execution artifacts with incremental updates

func NewExecutionTracker 

func NewExecutionTracker(outputDir string, planningArtifactPath string, feature string, totalTasks int) *ExecutionTracker

NewExecutionTracker creates a new execution tracker

func (*ExecutionTracker) AddPause 

func (t *ExecutionTracker) AddPause(pause ExecutionPause) error

AddPause records when execution paused for user input

func (*ExecutionTracker) AddReviewChecklistItem 

func (t *ExecutionTracker) AddReviewChecklistItem(item string) error

AddReviewChecklistItem adds a high-risk area for review

func (*ExecutionTracker) AddTaskProgress 

func (t *ExecutionTracker) AddTaskProgress(progress TaskProgress) error

AddTaskProgress adds progress for a completed task

func (*ExecutionTracker) Complete 

func (t *ExecutionTracker) Complete() error

Complete marks the execution as completed

func (*ExecutionTracker) GetFilePath 

func (t *ExecutionTracker) GetFilePath() string

GetFilePath returns the file path of the execution artifact

func (*ExecutionTracker) Initialize 

func (t *ExecutionTracker) Initialize() error

Initialize creates the initial execution artifact file

func (*ExecutionTracker) ResolvePause 

func (t *ExecutionTracker) ResolvePause(userResponse, resolution string) error

ResolvePause updates the latest pause entry with user feedback.

type FileModification 

type FileModification struct {
	Path          string
	LinesAdded    int
	LinesDeleted  int
	LinesModified int
}

FileModification tracks changes to a file

type Improvement 

type Improvement struct {
	Category    string // "Codebase Quality", "Architecture", "Performance", "Documentation"
	Title       string
	Observation string
	Suggestion  string
	Impact      string // Effort and benefit assessment
	Files       []string
}

Improvement represents opportunistic improvements found during review

type Issue 

type Issue struct {
	ID          int
	Severity    string // "critical", "quality", "nit"
	Category    string // "Security", "Correctness", etc.
	Title       string
	Description string
	Location    string // File and line number
	Fix         string // Suggested fix
}

Issue represents a problem found during review

type Layer 

type Layer struct {
	Name         string   // "Domain", "Application", "Infrastructure", "Interface"
	Files        []string // Files in this layer
	Dependencies []string // Layers this depends on
}

Layer represents a single architectural layer

type LayerMap 

type LayerMap struct {
	Layers []Layer
}

LayerMap shows the file → layer → dependencies mapping

type ModelClient 

type ModelClient = CompactionClient

ModelClient is retained as a backwards-compatible alias.

type Phase 

type Phase string

Phase represents the current workflow phase 

const (
	PhasePlanning  Phase = "planning"
	PhaseExecution Phase = "execution"
	PhaseReview    Phase = "review"
)

type PlanningArtifact 

type PlanningArtifact struct {
	Artifact
	Context           ContextSection
	Decisions         []ArchitectureDecision
	CodeContracts     []CodeContract
	LayerMap          LayerMap
	Tasks             []TaskBreakdown
	CrossCuttingScope CrossCuttingConcerns
}

PlanningArtifact represents a planning phase artifact

type PlanningGenerator 

type PlanningGenerator struct {
	// contains filtered or unexported fields
}

PlanningGenerator creates planning artifacts from structured data

func NewPlanningGenerator 

func NewPlanningGenerator(outputDir string) *PlanningGenerator

NewPlanningGenerator creates a new planning artifact generator

func (*PlanningGenerator) Generate 

func (g *PlanningGenerator) Generate(artifact *PlanningArtifact) (string, error)

Generate creates a planning artifact and writes it to disk Returns the file path and any error

type RelevantFile 

type RelevantFile struct {
	Path    string
	Reason  string
	Summary string
}

type ResearchBrief 

type ResearchBrief struct {
	Feature       string
	UserGoal      string
	Questions     []ResearchQuestion
	Risks         []string
	RelevantFiles []RelevantFile
	Decisions     []string
	Summary       string

	FilePath string
	Created  time.Time
	Updated  time.Time
	Status   string
}

ResearchBrief captures pre-implementation research notes.

type ResearchGenerator 

type ResearchGenerator struct {
	// contains filtered or unexported fields
}

ResearchGenerator persists research briefs as Markdown.

func NewResearchGenerator 

func NewResearchGenerator(outputDir string) *ResearchGenerator

NewResearchGenerator creates an artifact generator for research briefs.

func (*ResearchGenerator) Generate 

func (g *ResearchGenerator) Generate(brief *ResearchBrief) (string, error)

Generate saves the research brief to disk.

type ResearchQuestion 

type ResearchQuestion struct {
	Question string
	Answer   string
}

type ReviewArtifact 

type ReviewArtifact struct {
	Artifact
	PlanningArtifactPath      string
	ExecutionArtifactPath     string
	ReviewedAt                time.Time
	ReviewerModel             string
	Status                    string // "in_progress", "changes_requested", "approved"
	ValidationStrategy        ValidationStrategy
	ValidationResults         []ValidationResult
	IssuesFound               []Issue
	Iterations                []ReviewIteration
	OpportunisticImprovements []Improvement
	Approval                  *Approval
}

ReviewArtifact captures review validation and results

type ReviewGenerator 

type ReviewGenerator struct {
	// contains filtered or unexported fields
}

ReviewGenerator creates review artifacts

func NewReviewGenerator 

func NewReviewGenerator(outputDir string) *ReviewGenerator

NewReviewGenerator creates a new review artifact generator

func (*ReviewGenerator) Generate 

func (g *ReviewGenerator) Generate(artifact *ReviewArtifact) (string, error)

Generate creates a review artifact and writes it to disk

type ReviewIteration 

type ReviewIteration struct {
	Number      int
	Timestamp   time.Time
	IssuesFound int
	Status      string // "changes_requested", "approved"
	Notes       string
}

ReviewIteration tracks review cycles

type TaskBreakdown 

type TaskBreakdown struct {
	ID              int      // Task number
	Description     string   // What to implement
	FilePath        string   // File to create/modify
	Pseudocode      string   // Algorithmic approach
	Complexity      string   // Time/space complexity notes
	Maintainability string   // Maintainability assessment
	Dependencies    []int    // Task IDs this depends on
	Verification    []string // How to verify this task
}

TaskBreakdown represents a single task with implementation guidance

type TaskProgress 

type TaskProgress struct {
	TaskID              int
	Description         string
	Status              string // "pending", "in_progress", "completed", "failed"
	StartedAt           time.Time
	CompletedAt         *time.Time
	Duration            string
	FilesModified       []FileModification
	ImplementationNotes string
	Deviations          []Deviation
	TestsAdded          []TestResult
	CodeSnippet         string
}

TaskProgress represents progress on a single task

type TestResult 

type TestResult struct {
	Name     string
	Status   string // "pass", "fail"
	Coverage float64
}

TestResult captures test execution results

type TokenCounter 

type TokenCounter interface {
	// Count returns the number of tokens in the given text
	Count(text string) (int, error)
}

TokenCounter is an interface for counting tokens in text

type ValidationCheck 

type ValidationCheck struct {
	Name        string
	Status      string // "pass", "fail", "concern"
	Description string
	Issue       *Issue // If check failed or raised concern
}

ValidationCheck is an individual validation item

type ValidationResult 

type ValidationResult struct {
	Category string // "Security", "Correctness", "Conventions", etc.
	Status   string // "pass", "fail", "concern"
	Checks   []ValidationCheck
}

ValidationResult represents results for a validation category

type ValidationStrategy 

type ValidationStrategy struct {
	CriticalPath  []string // Ordered list of validation priorities
	HighRiskAreas []string // Areas flagged from execution
}

ValidationStrategy describes how review will validate the implementation

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.