Initialize v1 project planning

[phroi]

Why

Establish the planning foundation for v1 development — project definition, research, requirements, and a 7-phase roadmap.

Changes

• Add PROJECT.md with project definition and scope
• Add planning tool config (config.json)
• Add 5 research documents (architecture, features, pitfalls, stack, summary)
• Add REQUIREMENTS.md defining v1 requirements
• Add ROADMAP.md with 7-phase implementation plan and STATE.md for tracking

[gemini-code-assist]

Summary of Changes

Hello @phroi, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request establishes the foundational planning for the iCKB Stack v2 development. It introduces a comprehensive set of documentation that defines the project's scope, outlines detailed requirements, and maps out a strategic 7-phase roadmap. The included research documents provide deep dives into architectural considerations, feature prioritization, potential pitfalls, and the recommended technology stack, all aimed at guiding the migration to CCC-native APIs and the removal of legacy components.

Highlights

• Project Definition and Scope: A new PROJECT.md document has been added, outlining the iCKB Stack v2's purpose as a CCC-based TypeScript library suite, its core value, validated and active requirements, out-of-scope items, and key architectural decisions for the upcoming refactor.
• Comprehensive V1 Requirements: The REQUIREMENTS.md file details specific v1 requirements, categorized into SmartTransaction removal, CCC utility deduplication, and CCC UDT integration, along with a traceability matrix linking requirements to roadmap phases.
• Detailed 7-Phase Roadmap: A ROADMAP.md has been introduced, defining a 7-phase plan for the v1 milestone, focusing on the systematic removal of the SmartTransaction abstraction, adoption of CCC-native utilities, and integration of CCC's UDT patterns, with clear goals, dependencies, and success criteria for each phase.
• Extensive Research Documentation: Five new research documents (ARCHITECTURE.md, FEATURES.md, PITFALLS.md, STACK.md, SUMMARY.md) provide in-depth analysis of the current and proposed architecture, feature landscape, potential pitfalls, recommended technology stack changes, and an executive summary to guide the v1 development.
• Project State Tracking: A STATE.md file has been added to track the current progress, performance metrics, accumulated decisions, pending tasks, and identified blockers, ensuring continuous project oversight.

Changelog

• .planning/PROJECT.md
  • Added project definition, scope, requirements, context, constraints, and key decisions for iCKB Stack v2.
• .planning/REQUIREMENTS.md
  • Added detailed v1 and v2 requirements, including sections for SmartTransaction removal, CCC utility deduplication, and CCC Udt integration, along with a traceability matrix.
• .planning/ROADMAP.md
  • Added a 7-phase roadmap for the v1 milestone, detailing goals, dependencies, requirements, and success criteria for each phase of the refactoring.
• .planning/STATE.md
  • Added a document to track the current project state, progress, performance metrics, decisions, todos, and blockers.
• .planning/config.json
  • Added configuration for a planning tool, specifying workflow settings.
• .planning/research/ARCHITECTURE.md
  • Added research on the current and recommended architecture, detailing key changes for SmartTransaction removal and CCC UDT adoption, component responsibilities, data flow, patterns, and anti-patterns.
• .planning/research/FEATURES.md
  • Added research on the feature landscape, categorizing table stakes, differentiators, and anti-features, including dependencies, MVP definition, and competitor analysis.
• .planning/research/PITFALLS.md
  • Added research identifying critical pitfalls during migration, covering implicit behaviors, conservation law violations, exchange rate divergence, 64-output limits, and Molecule codec mismatches, with prevention and recovery strategies.
• .planning/research/STACK.md
  • Added research on the technology stack, focusing on CCC API adoption, local utility replacement, SmartTransaction removal strategy, UDT handling migration, and transaction completion patterns.
• .planning/research/SUMMARY.md
  • Added an executive summary of all research, key findings on stack, features, architecture, and pitfalls, along with implications for the roadmap and a confidence assessment.

Activity

• Initial planning documents for iCKB Stack v2 were created and added to the repository.
• The project definition, requirements, and a 7-phase roadmap were established.
• Comprehensive research on architecture, features, pitfalls, and the technology stack was conducted and documented.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

The pull request establishes a comprehensive planning foundation for the v1 development of iCKB Stack v2. It includes detailed research on architecture, features, pitfalls, and the technology stack, alongside a structured roadmap and requirements. The transition from the custom SmartTransaction to native CCC APIs is well-justified. However, there are several internal contradictions within the research documents—specifically regarding the Udt subclassing strategy and whether ccc.Transaction.getInputsCapacity() natively handles DAO profit—that should be resolved to ensure a consistent implementation path.

[phroi]

/gemini review

[gemini-code-assist]

Code Review

This pull request establishes a comprehensive and exceptionally well-structured foundation for the v1 development effort. The newly added planning documents (PROJECT.md, REQUIREMENTS.md, ROADMAP.md, etc.) are incredibly detailed, clear, and demonstrate a deep understanding of the project's goals, architecture, and potential risks. The research summaries are particularly impressive, providing a solid rationale for the proposed architectural changes, such as the removal of SmartTransaction and the adoption of CCC-native UDT patterns. The updates to existing documentation and dependencies are consistent with the overall plan. This is an excellent piece of work that sets the project up for success. I have no specific issues to raise.

[phroi]

LGTM

Phroi %153