Skip to content

Create productContext.md #17

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Create productContext.md #17

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 58 additions & 0 deletions cline_docs/productContext.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
# productContext.md

## What Is This Project?

`aligna` is a meta-framework for AI-native software collaboration.

It aims to reduce the need for repetitive prompting and manual instruction by embedding contextual knowledge directly within the project structure.

At the same time, it introduces the concept of **external reviewers**—humans or AI agents that provide oversight, validation, and feedback to ensure quality, guide decision-making, and constrain ungrounded behaviors.

## Why Does This Matter?

As AI systems become more capable, we face a fundamental challenge:
> How can we **control the quality** of autonomous AI activity within complex systems?

`aligna` addresses this by:
- Providing assistants with structured memory and navigation
- Delegating dynamic supervision to **reviewer agents** who can evaluate decisions, correct drift, and ensure adherence to purpose

## Who Is This For?

- Developers integrating AI into real software ecosystems
- Prompt engineers designing multi-agent workflows
- Reviewers (human or AI) assessing assistant outputs for accuracy, safety, or coherence
- Researchers exploring AI alignment through system-level design

## Design Principles

- **Static context guides active agents.**
- **Reviewers guide the agents.**
- **Bridge adapters connect agents to context.**
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The design principle "Bridge adapters connect agents to context." is introduced here. While concise, it might leave readers wondering about the nature or function of these "bridge adapters," as they aren't elaborated upon elsewhere in this document.

Could we consider adding a brief parenthetical explanation to clarify their role? This would help readers better grasp this aspect of the system's architecture.

Suggested change
- **Bridge adapters connect agents to context.**
- **Bridge adapters (e.g., dedicated modules or interfaces facilitating data exchange) connect agents to context.**

- **All logic is declarative and observable.**

## Key File Anchors

- `README.md`: Universal entrypoint
- `cline_docs/activeContext.md`: Current task state (bridge for Cline)
- `cline_docs/productContext.md`: Project identity and review philosophy
Comment on lines +36 to +38
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

In the "Key File Anchors" section, listing the file paths is helpful. To further improve navigability and user experience, could we make these Markdown links? This would allow readers to directly jump to these important documents from here.

(Please adjust paths if the assumed relative locations are incorrect. README.md is assumed to be in the parent directory, and activeContext.md in the current cline_docs directory.)

Suggested change
- `README.md`: Universal entrypoint
- `cline_docs/activeContext.md`: Current task state (bridge for Cline)
- `cline_docs/productContext.md`: Project identity and review philosophy
- [`README.md`](../README.md): Universal entrypoint
- [`cline_docs/activeContext.md`](activeContext.md): Current task state (bridge for Cline)
- [`cline_docs/productContext.md`](productContext.md): Project identity and review philosophy


## Long-Term Goal

To enable reliable, explainable, tool-agnostic AI workflows grounded in:
- Declarative architecture
- Embedded context
- Independent review
- Promptless cooperation
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The long-term goal of "Promptless cooperation" is quite compelling and a key differentiator. To make its significance even clearer to the reader, would it be beneficial to add a short explanatory phrase? This could help articulate the vision behind this ambitious goal more vividly.

Suggested change
- Promptless cooperation
- Promptless cooperation (i.e., AI components collaborating effectively based on shared context and goals, minimizing reliance on explicit, turn-by-turn prompting)


## Reviewer Layer (Emerging)

This project invites the integration of **reviewer agents**—entities that:
- Evaluate outputs
- Guide assistants back toward goals
- Record decisions and interventions for traceability

This layer will be prototyped via:
- Explicit reviewer prompts
- Human-in-the-loop validation
- Feedback-driven context updates